Ext: sg_ajax

License: GNU GPL, Version 2

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

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

TYPO3 version: >=9.5

About

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

The examples in this readme use jQuery, but of course 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

1. 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
            'Ajax\ControllerName' => 'myActionOne, myActionTwo',
        ], 'Vendor Name (default: SGalinski)'
    );
   

2. Add a controller in Classes/Controller/Ajax with the chosen name and extend it with this class:

   \SGalinski\SgAjax\Controller\Ajax\AbstractAjaxController
   

3. 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 the JavaScript.

   Place the link in a Fluid Template:

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

   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.