Basic Concepts

Overview of Drupal's Ajax API.

This page is based on the "Ajax API" documentation. 

Why Ajax?

Ajax is the process of dynamically updating parts of a page's HTML based on data from the server without requiring full page refresh. You can find events triggering Ajax requests all over Drupal, for example when selecting Views filters, Views pagers or forms widgets like autocomplete fields.

When a specified event takes place, like entering values in a textbox or clicking a button, a PHP callback is triggered. The callback function performs server-side logic and either

• returns updated markup to display new information on a page or form without a full page refresh, or 
• executes JavaScript commands which can display dialog boxes, alter CSS on the page or execute custom JavaScript code.

Any valid DOM event can be used to trigger Ajax requests, simply omit the 'on' portion of the event. For example 'onclick' becomes 'click', 'onchange' is 'change'. Find example code on the Ajax Forms documentation page. Examples events:

• Clicking a button
• Pressing a key
• Entering values in a textbox
• Selecting a checkbox
• Moving the mouse

Methods for triggering Ajax requests

Trigger Ajax request from a form

Add an '#ajax' parameter with appropriate values to your form element.

See the AJAX Forms Documentation Page for details on triggering ajax and handling callbacks from a drupal form.
See also

• Form API Guide
• Form Generation API topic

Trigger Ajax request with a link

Add class 'use-ajax' to a link. The link will be loaded using an Ajax call. When using this method, the href of the link can contain '/nojs/' as part of the path. When Ajax JavaScript processes the page, it will convert this to '/ajax/'. The server is then able to easily tell if this request was made through an actual Ajax request or in a degraded state, and respond appropriately.

Trigger Ajax request with a submit button

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.

Autocomplete on text fields

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.

Drupal Ajax Conventions

Replacing markup

It is best practice to use an element's id attribute to target it for replacement to avoid any chance of the wrong element or multiple elements being replaced unless that is specifically required. In order to maintain the replaceability of that element, the replacement render array or HTML markup should contain a wrapper element with the same id as the element that was being replaced.

When working with render arrays, if such a wrapper is not automatically included it is common practice to use the '#prefix' and '#suffix' render variables at the top level to provide one.