Adding AJAX callback events to form fields allows to dynamically update fields and other markup, while users interact with the forms.
More general information about Drupal and Ajax can be found at Drupal Ajax API Guide and Drupal's Ajax API documentation (at api.drupal.org).
Some working examples can be found in the Examples for Developers modules, specifically in the AJAX Example submodule, see its Form folder.
Full list of available #ajax properties
The #ajax property of a form element is an array. Here are the details of its known 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 under "Setting up a callback to process Ajax".
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. - wrapper: The HTML 'id' attribute of the area where the content returned by the callback should be placed. Note that callbacks have a choice of returning content or JavaScript commands; 'wrapper' is used for content returns.
- 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.
- event: The JavaScript event to respond to. This is selected automatically for the type of form element; provide a value to override the default. See RenderElement::preRenderAjaxForm for the type-specific defaults. Especially note that the event for submit, button and image_button is "mousedown" (not "click") for example!
- prevent: A JavaScript event to prevent when the event is triggered. For example, if you use event 'mousedown' on a button, you might want to prevent 'click' events from also being triggered.
- disable-refocus: Disable automatic refocus after an ajax call.
- progress: An array indicating how to show Ajax processing progress. Can contain one or more of these elements:
- type: Type of indicator: 'throbber' (default), 'bar' or 'none'.
- 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.
- url: A \Drupal\Core\Url to which to submit the Ajax request. If omitted, defaults to either the same URL as the form or link destination is for someone with JavaScript disabled, or a slightly modified version (e.g., with a query parameter added, removed, or changed) of that URL if necessary to support Drupal's content negotiation. It is recommended to omit this key and use Drupal's content negotiation rather than using substantially different URLs between Ajax and non-Ajax.
Note that if you use this url property, your route controller will be triggered with only the information you provide in the URL.
