README

Repository: https://gitlab.sgalinski.de/typo3/sg_ajax

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_ajax

About

Offers an easy-to-use API for implementing AJAX requests within your TYPO3 Extensions.

The examples in this readme use jQuery, but this extension can be used with any other JavaScript library that offers an AJAX api.

Usage

Generally, you need an Ajax Controller receiving the request and register it with sg_ajax.

Depending on your use case, the following tasks are necessary:

Frontend Ajax registration

Ensure to add a map entry to the route enhancers!

   routeEnhancers:
     PageTypeSuffix:
       map:
         sgajax.html: 1595576051

Call the AjaxRegistration::configureAjaxFrontendPlugin function in the ext_localconf.php of your extension

 \SGalinski\SgAjax\Service\AjaxRegistration::configureAjaxFrontendPlugin('Your extension name like: sg_ajax', [
         // ControllerName without the word Controller
         // must be located in the directory ext\Classes\Controller\Ajax
         \Vendor\ExtensionName\Controller\Ajax\AjaxController::class => 'myActionOne, myActionTwo',
     ]
 );

Add a controller in Classes/Controller/Ajax with the chosen name and extend it with this class:
```
\SGalinski\SgAjax\Controller\Ajax\AbstractAjaxController
```

Endpoint for Javascript usage

You should always use the ViewHelpers provided to generate the Ajax Urls. You can do so by creating the Ajax link and read it in JavaScript.

Place the link in a Fluid Template:

 {namespace sgajax=SGalinski\SgAjax\ViewHelpers}
 <sgajax:link.ajax class="ajaxlink" style="display: none;" extensionName="ProjectThemeMegamenu" controller="Ajax\AjaxController" action="myActionOne">#</sgajax:link.ajax>

There is also an uri.ajax viewhelper to only return the URI if you want to add it to a data attribute. It Might be more convenient in many situations.

You can add parameters in the form: `tx_sgajax[parameters][query]`.

Example: JavaScript usage with our Request class:

 Request.fetch(document.querySelector('.ajaxlink').href, {
     tx_sgajax: {
         parameters: {parameterName: parameterValue} // Add optional parameters here
     }
 }, 'GET' /* Use the correct verb here */).then((result) => {
     // Do something
 });

Example with jQuery:

 $.post(
     $('.ajaxlink').attr('href'),
         {
         tx_sgajax: {
             parameters: {
                 one: parameter
             }
         }
     }
 );

Developer Guide

Controller Classes

Ajax/AbstractAjaxController

This class extends TYPO3\CMS\Extbase\Mvc\Controller\ActionController and should be used instead if your controller needs to be able to process AJAX requests.

function processRequest

Extends the parent function by providing exception handling specific to AJAX calls.

function returnData

Gives the option to return JSON instead of a Fluid view.

Ajax/FrontendDispatcher

This is the main entrypoint of the sgajax functionality. It provides a middleware that handles the request if tx_sgajax is given as a parameter. This is done by injecting the parameters into a TypoScript PAGE configuration that takes over the Extbase bootstrap process and proceeds with the request as it would have been called directly this way.

Service Classes

AjaxRegistration

Provides two static functions to register or configure your AJAX plugins.

function registerAjaxFrontendPlugin

This needs to be called in your ext_tables.php to register your frontend plugin.

function configureAjaxFrontendPlugin

This needs to be called in your ext_localconf.php to configure your frontend plugin.

ViewHelper

Link/AjaxViewHelper

This ViewHelper renders the ajax link for the frontend. You need to give it the extensionName, controller and action to be able to generate the link.

Uri/AjaxViewHelper

This ViewHelper renders the ajax url for the frontend. You need to give it the extensionName, controller and action to be able to generate the link.

sgalinski / sg-ajax

Maintainers

Details