Ajax in the backend, client-side

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 withQueryArguments() 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();

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}`);
});

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();