- 8.2.x core/core.api.php ajax
- 8.0.x core/core.api.php ajax
- 8.1.x core/core.api.php ajax
- 8.3.x core/core.api.php ajax
- 7.x includes/ajax.inc ajax
Overview for Drupal's Ajax API.
Overview of Ajax
Many different events can trigger Ajax responses, including:
- Clicking a button
- Pressing a key
- Moving the mouse
Ajax responses in forms
Forms that use the Drupal Form API (see the Form API topic for more information about forms) can trigger AJAX responses. Here is an outline of the steps:
- Add property '#ajax' to a form element in your form array, to trigger an Ajax response.
- Write an Ajax callback to process the input and respond.
See sections below for details on these two steps.
Adding Ajax triggers to a form
As an example of adding Ajax triggers to a form, consider editing a date format, where the user is provided with a sample of the generated date output as they type. To accomplish this, typing in the text field should trigger an Ajax response. This is done in the text field form array element in \Drupal\config_translation\FormElement\DateFormat::getFormElement():
'#ajax' => array( 'callback' => 'Drupal\config_translation\FormElement\DateFormat::ajaxSample', 'event' => 'keyup', 'progress' => array( 'type' => 'throbber', 'message' => NULL, ), ),
As you can see from this example, the #ajax property for a form element is an array. Here are the details of its elements, all of which are optional:
- callback: The callback to invoke to handle the server side of the Ajax event. More information on callbacks is below in Setting up a callback to process Ajax.
- method: The jQuery method for placing the new content (used with 'wrapper'). Valid options are 'replaceWith' (default), 'append', 'prepend', 'before', 'after', or 'html'. See http://api.jquery.com/category/manipulation/ for more information on these methods.
- effect: The jQuery effect to use when placing the new HTML (used with 'wrapper'). Valid options are 'none' (default), 'slide', or 'fade'.
- speed: The effect speed to use (used with 'effect' and 'wrapper'). Valid options are 'slow' (default), 'fast', or the number of milliseconds the effect should run.
- progress: An array indicating how to show Ajax processing progress. Can
contain one or more of these elements:
- type: Type of indicator: 'throbber' (default) or 'bar'.
- message: Translated message to display.
- url: For a bar progress indicator, URL path for determining progress.
- interval: For a bar progress indicator, how often to update it.
Setting up a callback to process Ajax
Once you have set up your form to trigger an Ajax response (see Adding Ajax triggers to a form above), you need to write some PHP code to process the response. If you use 'path' in your Ajax set-up, your route controller will be triggered with only the information you provide in the URL. If you use 'callback', your callback method is a function, which will receive the $form and $form_state from the triggering form. You can use $form_state to get information about the data the user has entered into the form. For instance, in the above example for the date format preview, \Drupal\config_translation\FormElement\DateFormat\ajaxSample() does this to get the format string entered by the user:
$format_value = \Drupal\Component\Utility\NestedArray::getValue( $form_state->getValues(), $form_state->getTriggeringElement()['#array_parents']);
Once you have processed the input, you have your choice of returning HTML markup or a set of Ajax commands. If you choose to return HTML markup, you can return it as a string or a renderable array, and it will be placed in the defined 'wrapper' element (see documentation above in Adding Ajax triggers to a form). In addition, any messages returned by drupal_get_messages(), themed as in status-messages.html.twig, will be prepended.
To return commands, you need to set up an object of class \Drupal\Core\Ajax\AjaxResponse, and then use its addCommand() method to add individual commands to it. In the date format preview example, the format output is calculated, and then it is returned as replacement markup for a div like this:
$response = new AjaxResponse(); $response->addCommand(new ReplaceCommand( '#edit-date-format-suffix', '<small id="edit-date-format-suffix">' . $format . '</small>')); return $response;
The individual commands that you can return implement interface \Drupal\Core\Ajax\CommandInterface. Available commands provide the ability to pop up alerts, manipulate text and markup in various ways, redirect to a new URL, and the generic \Drupal\Core\Ajax\InvokeCommand, which invokes an arbitrary jQuery command.
As noted above, status messages are prepended automatically if you use the 'wrapper' method and return HTML markup. This is not the case if you return commands, but if you would like to show status messages, you can add
array('#type' => 'status_messages')
to a render array, use drupal_render() to render it, and add a command to place the messages in an appropriate location.
Other methods for triggering Ajax
Here are some additional methods you can use to trigger Ajax responses in Drupal:
- Add class 'use-ajax-submit' to a submit button in a form. The form will then be submitted via Ajax to the path specified in the #action. Like the ajax-submit class on links, this path will have '/nojs/' replaced with '/ajax/' so that the submit handler can tell if the form was submitted in a degraded state or not.
- Add property '#autocomplete_route_name' to a text field in a form. The route controller for this route must return an array of options for autocomplete, as a \Symfony\Component\HttpFoundation\JsonResponse object. See the Routing topic for more information about routing.
core.api.php, line 2304
- Documentation landing page and topics, plus core library hooks.
||An AJAX command for adding css to the page via ajax.|
||An AJAX command for calling the jQuery after() method.|
||Provides a render element for adding Ajax to a render element.|
||JSON response object for AJAX requests.|
||An AJAX command for calling the jQuery append() method.|
||An AJAX command for calling the jQuery before() method.|
||An AJAX command for marking HTML elements as changed.|
||Defines an AJAX command that closes the current active dialog.|
||Defines an AJAX command that closes the currently visible modal dialog.|
||An AJAX command for calling the jQuery css() method.|
||An AJAX command for implementing jQuery's data() method.|
||AJAX command for calling the jQuery html() method.|
||Generic AJAX command for inserting content.|
||AJAX command for invoking an arbitrary jQuery method.|
||Defines an AJAX command to open certain content in a dialog.|
||Defines an AJAX command to open certain content in a dialog in a modal dialog.|
||Defines an AJAX command to open content in a dialog in a off-canvas tray.|
||AJAX command for calling the jQuery insert() method.|
||Defines an AJAX command to set the window.location, loading that URL.|
||AJAX command for calling the jQuery remove() method.|
||AJAX command for calling the jQuery replace() method.|
||AJAX command for resetting the striping on a table.|
||Defines an AJAX command that sets jQuery UI dialog properties.|
||Defines an AJAX command that sets jQuery UI dialog properties.|
||AJAX command for updating the value of a hidden form_build_id input element on a form. It requires the form passed in to have keys for both the old build ID in #build_id_old and the new build ID in #build_id.|