Drupal 8 API: Ajax

Pre-requisites

• Forms

Interacting with the server, without reloading the entire page

Back when it was first proposed that browsers could contact servers to load data, or small fragments of HTML, without reloading the whole page, people referred to it using the name "Ajax". This originally stood for Asynchronous Javascript And XML, but nowadays is a catch-all term for communicating between the browser and server "in the background", while the site visitor is still presented with a page.

These days, Drupal uses JSON rather than XML to communicate, but otherwise the principle is the same:

1. Detect some user input or interaction in the browser.
2. Make a background HTTP call to the server, while letting the site visitor know something is happening.
3. Act on the result.

To accomplish this, we need (in theory at least) the following pieces:

• A route—a path with a handler method or class—for Drupal to manage incoming Ajax requests.
• A form (or maybe some links or other buttons) for the site visitor to click on.
• Some Javascript in the browser to make the initial call, and do something with the result.

We've discussed routing and forms previously, so here we extend those examples to perform an Ajax call. Our example will do the following:

1. When a user fills in the existing form at /tutorial/form, send the data to the server for "validation".
2. Show a spinner while waiting for the server to respond.
3. When the response returns, alert the user, then submit the form anyway.

As we'll see, Drupal gives us a comprehensive toolkit with which to accomplish this.

Configure an Ajax action to use a class and method

An Ajax request, made as part of some existing form, uses the same path as the form but with some query parameters. If you use some kind of browser debugger tool, you might see the example below making requests to a URL like /tutorial/form?ajax_form=1&_wrapper_format=drupal_ajax. This tells Drupal to invoke the form to handle the request, but then switch to a different configured class and method to specifically handle it as Ajax.

To configure this, we modify the existing buildForm() method on our form, to return an extra #ajax key in its structured data:

<?php
/* ... (unchanged) ... */
class TutorialForm extends FormBase {
  /* ... (unchanged) ... */
  public function buildForm(array $form, FormStateInterface $form_state) {
    $form['phone'] = [
      '#type' => 'tel',
      '#title' => $this->t('Your telephone number'),
    ];
    $form['go'] = [
      '#type' => 'submit',
      '#value' => $this->t('Go'),
 
      // Modifications below.
      '#ajax' => [
        'callback' => 'Drupal\d8api\Form\TutorialForm::respondToAjax',
        'event' => 'click',
        'progress' => ['type' => 'throbber', 'message' => NULL],
      ],
    ];
 
    return $form;
  }
 
  /* ... (unchanged) ... */
}

In the example above, we give the #ajax configuration sub-array three keys:

callback

Which class and method (yet to be written) will respond to the Ajax call. This could involve any class, but for simplicity's sake we're going to add a new method to the existing TutorialForm class.

event

What event in the browser should trigger the Ajax call. This is a click event on the "Go" button. Note that, for accessibility reasons, Drupal's Javascript will also deal with keypress events e.g. submitting the form by tabbing to the button and pressing "enter".

progress

What hint should be given to the site visitor that an Ajax call is in progress. Here we specify the throbber (we'll see it in action below) but no other message.

This configuration is all that's required for the Javascript behaviours in the browser: Drupal will build the rest.

Add a class method to respond to the browser's Ajax call

To match our configuration above, we need to add a respondToAjax() method to the TutorialForm class.

Ajax-responding methods need to return a special AjaxResponse object. This object can chain any arbitrary Ajax commands: Drupal core comes with a number of PHP objects that correspond to Javascript and jQuery methods in the browser; you can also create your own classes, and instantiate them as objects to chain them; alternatively, existing objects like InvokeCommand let you

Below we implement a method which, when the response reaches the browser, causes the following three Javascript actions to occur in order:

1. Pop up a native browser alert box with the submitted user input in it.
2. Change the internal build ID of the form. Forms are given a unique build ID by Drupal, but if your Ajax call might be modifying the form, it's good practice to change this build ID.
3. Submit the form, referencing the new build ID in order to find the form in the browser.

Here's the new method:

<?php
 
namespace Drupal\d8api\Form;
 
use Drupal\Core\Ajax\AjaxResponse;
use Drupal\Core\Ajax\AlertCommand;
use Drupal\Core\Ajax\InvokeCommand;
use Drupal\Core\Ajax\UpdateBuildIdCommand;
/* ... (unchanged) ... */
class TutorialForm extends FormBase {
  /* ... (with previous changes) ... */
  /**
   * AJAX response: alert contents of input field, update form and save it.
   *
   * @param array $form
   *   Form API array structure.
   * @param array $form_state
   *   Form state information.
   *
   * @return AjaxResponse
   *   Response object.
   */
  public static function respondToAjax(array $form, FormStateInterface $form_state) {
    $response = new AjaxResponse();
    $message = 'Your phone number is ' . $form_state->getValue('phone');
    $submit_selector = 'form:has(input[name=form_build_id][value='
      . $form['#build_id'] . '])';
 
    $response->addCommand(new AlertCommand($message));
    $response->addCommand(new UpdateBuildIdCommand($form['#build_id_old'], $form['#build_id']));
    $response->addCommand(new InvokeCommand($submit_selector, 'submit'));
 
    return $response;
  }
}

Arguably, you might not want to submit forms on the site visitor's behalf—it might not be best practice in some situations—but this is only meant to serve as an example.

What you should see

If you navigate to /tutorial/form, you should see the form as before:

Forms - tutorial form.png

However, when you now press the "Go" button, a blue spinner appears beside the button, and shortly afterwards an alert box appears:

Drupal 8 Ajax spinner and alert.png

If you then dismiss the alert box, the form "submits itself" and you should see the resulting page with a message, in the same way as before we added Ajax to the form:

Forms - tutorial form submitted.png

If you can see all this, then congratulations! you have successfully added Ajax to a form in Drupal.

Further reading etc.

• Drupal 8 API: Ajax
• Ajax API has incomplete example; references obsolete module instead