Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Client-Side Programming

TYPO3 Core ships an API to send AJAX requests to the server. This API is based on the fetch API, which is implemented in every modern browser (e.g. Chrome, Safari, Firefox, Edge).

Note

TYPO3 ships jQuery as well, but is considered discouraged for new code.

Prepare a Request

To be able to send a request, the module TYPO3/CMS/Core/Ajax/AjaxRequest must be imported. To prepare a request, create a new instance of AjaxRequest per request and pass the url as the constructor argument:

let request = new AjaxRequest('https://example.org/my-endpoint');

The API offers a method withQueryString() which allows to attach a query string to the URL. This comes in handy if the query string is programmatically generated. The method returns a clone of the AjaxRequest object. It's possible to pass either strings, arrays or objects as an argument.

Example:

const qs = {
  foo: 'bar',
  bar: {
    baz: ['foo', 'bencer']
  }
};
request = request.withQueryArguments(qs);

// The query string compiles to ?foo=bar&bar[baz][0]=foo&bar[baz][1]=bencer

The method detects whether the URL already contains a query string and appends the new query string in a proper format.

Send a Request

The API offers some methods to actually send the request:

  • get()

  • post()

  • put()

  • delete()

Each of these methods set the corresponding request method (GET, POST, PUT, DELETE). post(), put() and delete() accept the following arguments:

data

| Condition: required | Type: string | object |

The payload to be sent as body in the request.

init

| Condition: optional | Type: object | Default: '{}' |

Additional request configuration to be set

The method get() accepts the init argument only.

Example:

let promise = request.get();

Note

The API presets the request configuration with {credentials: 'same-origin', signal: AbortController.signal}.

The body of the request is automatically converted to a FormData object, if the submitted payload is an object. To send a JSON-encoded object instead, set the Content-Type header to application/json. If the payload is a string, no conversion will happen, but it's still recommended to set proper headers.

Example:

const json = {foo: 'bar'};
let promise = request.post(json, {
  headers: {
    'Content-Type': 'application/json; charset=utf-8'
  }
});

Handle the Response

In the examples above promise is, as the name already spoils, a Promise object. To fetch the actual response, we'll make use of then():

promise.then(async function (response) {
  const responseText = await response.resolve();
  console.log(responseText);
});

response is an object of type AjaxResponse shipped by TYPO3 (TYPO3/CMS/Core/Ajax/AjaxResponse). The object is a simple wrapper for the original Response object. AjaxResponse exposes the following methods which eases the handling with responses:

  • resolve() - returns the correct response based on the received Content-Type header, either plaintext or a JSON object

  • raw() - returns the original Response object

Of course a request may fail for various reasons. In such case, a second function may be passed to then(), which handles the exceptional case. The function may receive a ResponseError object (TYPO3/CMS/Core/Ajax/ResponseError) which contains the received response.

promise.then(async function (response) {}, function (error) {
  console.error(`The request failed with ${error.response.status}: ${error.response.statusText}`);
});

Hint

The fetch API handles responses with faulty statuses like 404 or 500 still as "successful", but sets the response's ok field to false. The AJAX API converts such responses into errors for convenience reasons.

Abort a Request

In some cases it might be necessary to abort a running request. The AJAX API has you covered then, an instance of AbortController is attached to each request. To abort the request, just call the abort() method:

request.abort();