Drupal javascript API documentation

new Ajax(baseopt, elementopt, elementSettings)

Source:

ajax.js, line 399

Ajax constructor. The Ajax request returns an array of commands encoded in JSON, which is then executed to make any changes that are necessary to the page. Drupal uses this file to enhance form elements with `#ajax['url']` and `#ajax['wrapper']` properties. If set, this file will automatically be included to provide Ajax capabilities.

Parameters:

Name	Type	Attributes	Description
`base`	string	<optional>	Base parameter of Drupal.Ajax constructor
`element`	HTMLElement	<optional>	Element parameter of Drupal.Ajax constructor, element on which event listeners will be bound.
`elementSettings`	Drupal.Ajax~elementSettings		Settings for this Ajax object.

Members

(static, constant) AJAX_REQUEST_PARAMETER :string

Source:

ajax.js, line 674

Default Value:

_drupal_ajax

Request parameter to indicate that a request is a Drupal Ajax request.

Type:

string

$form :jQuery

Source:

ajax.js, line 456

Type:

jQuery

commands :Drupal.AjaxCommands

Source:

ajax.js, line 422

Type:

Drupal.AjaxCommands

element :HTMLElement

Source:

ajax.js, line 443

Type:

HTMLElement

elementSettings :Drupal.Ajax~elementSettings

Source:

ajax.js, line 448

Type:

Drupal.Ajax~elementSettings

instanceIndex :boolean|number

Source:

ajax.js, line 427

Type:

boolean | number

options :object

Source:

ajax.js, line 494

Properties:

Name	Type	Default	Description
`url`	string		Ajax URL to be called.
`data`	object		Ajax payload.
`beforeSerialize`	function		Implement jQuery beforeSerialize function to call Drupal.Ajax#beforeSerialize.
`beforeSubmit`	function		Implement jQuery beforeSubmit function to call Drupal.Ajax#beforeSubmit.
`beforeSend`	function		Implement jQuery beforeSend function to call Drupal.Ajax#beforeSend.
`success`	function		Implement jQuery success function to call Drupal.Ajax#success.
`complete`	function		Implement jQuery success function to clean up ajax state and trigger an error if needed.
`dataType`	string	`'json'`	Type of the response expected.
`type`	string	`'POST'`	HTTP method to use for the Ajax request.

Options for the jQuery.ajax function.

Type:

object

url :string

Source:

ajax.js, line 483

Processed Ajax URL.

Type:

string

wrapper :string

Source:

ajax.js, line 437

Type:

string

Methods

beforeSend(xmlhttprequest, options)

Source:

ajax.js, line 859

Prepare the Ajax request before it is sent.

Parameters:

Name	Type	Description
`xmlhttprequest`	XMLHttpRequest	Native Ajax object.
`options`	object	jQuery.ajax options.

beforeSerialize(elementopt, options)

Source:

ajax.js, line 811

Handler for the form serialization. Runs before the beforeSend() handler (see below), and unlike that one, runs before field data is collected.

Parameters:

Name	Type	Attributes	Description
`element`	object	<optional>	Ajax object's `elementSettings`.
`options`	object		jQuery.ajax options.

beforeSubmit(formValues, element, options)

Source:

ajax.js, line 846

Modify form values prior to form submission.

Parameters:

Name	Type	Description
`formValues`	Array.<object>	Processed form values.
`element`	jQuery	The form node as a jQuery object.
`options`	object	jQuery.ajax options.

commandExecutionQueue(response, status) → {Promise}

Source:

ajax.js, line 1022

Helper method to make sure commands are executed in sequence.

Parameters:

Name	Type	Description
`response`	Array.<Drupal.AjaxCommands~commandDefinition>	Drupal Ajax response.
`status`	number	XMLHttpRequest status.

Returns:

The promise that will resolve once all commands have finished executing.

Type: Promise

error(xmlhttprequest, uri, customMessageopt)

Source:

ajax.js, line 1176

Handler for the form redirection error.

Parameters:

Name	Type	Attributes	Description
`xmlhttprequest`	object		Native XMLHttpRequest object.
`uri`	string		Ajax Request URI.
`customMessage`	string	<optional>	Extra message to print with the Ajax error.

eventResponse(element, event)

Source:

ajax.js, line 761

Handle an event that triggers an Ajax response. When an event that triggers an Ajax response happens, this method will perform the actual Ajax call. It is bound to the event using bind() in the constructor, and it uses the options specified on the Ajax object.

Parameters:

Name	Type	Description
`element`	HTMLElement	Element the event was triggered on.
`event`	jQuery.Event	Triggered event.

execute() → {object}

Source:

ajax.js, line 687

Execute the ajax request. Allows developers to execute an Ajax request manually without specifying an event to respond to.

Returns:

Returns the jQuery.Deferred object underlying the Ajax request. If pre-serialization fails, the Deferred will be returned in the rejected state.

Type: object

getEffect(response) → {object}

Source:

ajax.js, line 1144

Build an effect object to apply an effect when adding new HTML.

Parameters:

Name Type Description

response

object

Drupal Ajax response.

Properties

Name	Type	Attributes	Description
`effect`	string	<optional>	Override the default value of Drupal.Ajax#elementSettings.
`speed`	string \| number	<optional>	Override the default value of Drupal.Ajax#elementSettings.

Returns:

Returns an object with `showEffect`, `hideEffect` and `showSpeed` properties.

Type: object

keypressResponse(element, event)

Source:

ajax.js, line 725

Handle a key press. The Ajax object will, if instructed, bind to a key press response. This will test to see if the key press is valid to trigger this event and if it is, trigger it for us and prevent other keypresses from triggering. In this case we're handling RETURN and SPACEBAR keypresses (event codes 13 and 32. RETURN is often used to submit a form when in a textfield, and SPACE is often used to activate an element without submitting.

Parameters:

Name	Type	Description
`element`	HTMLElement	Element the event was triggered on.
`event`	jQuery.Event	Triggered event.

setProgressIndicatorBar()

Source:

ajax.js, line 964

Sets the progress bar progress indicator.

setProgressIndicatorFullscreen()

Source:

ajax.js, line 1006

Sets the fullscreen progress indicator.

setProgressIndicatorThrobber()

Source:

ajax.js, line 990

Sets the throbber progress indicator.

success(response, status) → {Promise}

Source:

ajax.js, line 1052

Handler for the form redirection completion.

Parameters:

Name	Type	Description
`response`	Array.<Drupal.AjaxCommands~commandDefinition>	Drupal Ajax response.
`status`	number	XMLHttpRequest status.

Returns:

The promise that will resolve once all commands have finished executing.

Type: Promise

Type Definitions

elementSettings

Source:

ajax.js, line 339

Properties:

Name Type Attributes Default Description

url string Target of the Ajax request.

event string <optional>
<nullable> Event bound to settings.element which will trigger the Ajax request.

keypress boolean <optional> true Triggers a request on keypress events.

selector string <nullable> jQuery selector targeting the element to bind events to or used with Drupal.AjaxCommands.

effect string <optional> 'none' Name of the jQuery method to use for displaying new Ajax content.

speed string | number <optional> 'none' Speed with which to apply the effect.

method string <optional> Name of the jQuery method used to insert new content in the targeted element.

progress

object

Settings for the display of a user-friendly loader.

Properties

Name	Type	Attributes	Default	Description
`type`	string	<optional>	`'throbber'`	Type of progress element, core provides `'bar'`, `'throbber'` and `'fullscreen'`.
`message`	string	<optional>	`Drupal.t('Please wait...')`	Custom message to be used with the bar indicator.

submit

object

Extra data to be sent with the Ajax request.

Properties

Name	Type	Attributes	Default	Description
`js`	boolean	<optional>	`true`	Allows the PHP side to know this comes from an Ajax request.

dialog object <optional> Options for Drupal.dialog.

dialogType string <optional> One of `'modal'` or `'dialog'`.

prevent string <optional> List of events on which to stop default action and stop propagation.

Settings for an Ajax object.

Type:

object