4 * Provides Ajax page updating via jQuery $.ajax (Asynchronous JavaScript and XML).
6 * Ajax is a method of making a request via JavaScript while viewing an HTML
7 * page. The request returns an array of commands encoded in JSON, which is
8 * then executed to make any changes that are necessary to the page.
10 * Drupal uses this file to enhance form elements with #ajax['path'] and
11 * #ajax['wrapper'] properties. If set, this file will automatically be included
12 * to provide Ajax capabilities.
15 Drupal
.ajax
= Drupal
.ajax
|| {};
17 Drupal
.settings
.urlIsAjaxTrusted
= Drupal
.settings
.urlIsAjaxTrusted
|| {};
20 * Attaches the Ajax behavior to each Ajax form element.
22 Drupal
.behaviors
.AJAX
= {
23 attach: function (context
, settings
) {
24 // Load all Ajax behaviors specified in the settings.
25 for (var base
in settings
.ajax
) {
26 if (!$('#' + base
+ '.ajax-processed').length
) {
27 var element_settings
= settings
.ajax
[base
];
29 if (typeof element_settings
.selector
== 'undefined') {
30 element_settings
.selector
= '#' + base
;
32 $(element_settings
.selector
).each(function () {
33 element_settings
.element
= this;
34 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
37 $('#' + base
).addClass('ajax-processed');
41 // Bind Ajax behaviors to all items showing the class.
42 $('.use-ajax:not(.ajax-processed)').addClass('ajax-processed').each(function () {
43 var element_settings
= {};
44 // Clicked links look better with the throbber than the progress bar.
45 element_settings
.progress
= { 'type': 'throbber' };
47 // For anchor tags, these will go to the target of the anchor rather
48 // than the usual location.
49 if ($(this).attr('href')) {
50 element_settings
.url
= $(this).attr('href');
51 element_settings
.event
= 'click';
53 var base
= $(this).attr('id');
54 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
57 // This class means to submit the form to the action using Ajax.
58 $('.use-ajax-submit:not(.ajax-processed)').addClass('ajax-processed').each(function () {
59 var element_settings
= {};
61 // Ajax submits specified in this manner automatically submit to the
62 // normal form action.
63 element_settings
.url
= $(this.form
).attr('action');
64 // Form submit button clicks need to tell the form what was clicked so
65 // it gets passed in the POST request.
66 element_settings
.setClick
= true;
67 // Form buttons use the 'click' event rather than mousedown.
68 element_settings
.event
= 'click';
69 // Clicked form buttons look better with the throbber than the progress bar.
70 element_settings
.progress
= { 'type': 'throbber' };
72 var base
= $(this).attr('id');
73 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
81 * All Ajax objects on a page are accessible through the global Drupal.ajax
82 * object and are keyed by the submit button's ID. You can access them from
83 * your module's JavaScript file to override properties or functions.
85 * For example, if your Ajax enabled button has the ID 'edit-submit', you can
86 * redefine the function that is called to insert the new content like this
87 * (inside a Drupal.behaviors attach block):
89 * Drupal.behaviors.myCustomAJAXStuff = {
90 * attach: function (context, settings) {
91 * Drupal.ajax['edit-submit'].commands.insert = function (ajax, response, status) {
92 * new_content = $(response.data);
93 * $('#my-wrapper').append(new_content);
94 * alert('New content was appended to #my-wrapper');
100 Drupal
.ajax = function (base
, element
, element_settings
) {
105 selector
: '#' + base
,
108 method
: 'replaceWith',
111 message
: Drupal
.t('Please wait...')
118 $.extend(this, defaults
, element_settings
);
120 this.element
= element
;
121 this.element_settings
= element_settings
;
123 // Replacing 'nojs' with 'ajax' in the URL allows for an easy method to let
124 // the server detect when it needs to degrade gracefully.
125 // There are five scenarios to check for:
127 // 2. /nojs$ - The end of a URL string.
128 // 3. /nojs? - Followed by a query (with clean URLs enabled).
129 // E.g.: path/nojs?destination=foobar
130 // 4. /nojs& - Followed by a query (without clean URLs enabled).
131 // E.g.: ?q=path/nojs&destination=foobar
132 // 5. /nojs# - Followed by a fragment.
133 // E.g.: path/nojs#myfragment
134 this.url
= element_settings
.url
.replace(/\/nojs(\/|$|\?|&|#)/g, '/ajax$1');
135 // If the 'nojs' version of the URL is trusted, also trust the 'ajax' version.
136 if (Drupal
.settings
.urlIsAjaxTrusted
[element_settings
.url
]) {
137 Drupal
.settings
.urlIsAjaxTrusted
[this.url
] = true;
140 this.wrapper
= '#' + element_settings
.wrapper
;
142 // If there isn't a form, jQuery.ajax() will be used instead, allowing us to
143 // bind Ajax to links as well.
144 if (this.element
.form
) {
145 this.form
= $(this.element
.form
);
148 // Set the options for the ajaxSubmit function.
149 // The 'this' variable will not persist inside of the options object.
154 beforeSerialize: function (element_settings
, options
) {
155 return ajax
.beforeSerialize(element_settings
, options
);
157 beforeSubmit: function (form_values
, element_settings
, options
) {
159 return ajax
.beforeSubmit(form_values
, element_settings
, options
);
161 beforeSend: function (xmlhttprequest
, options
) {
163 return ajax
.beforeSend(xmlhttprequest
, options
);
165 success: function (response
, status
, xmlhttprequest
) {
166 // Sanity check for browser support (object expected).
167 // When using iFrame uploads, responses must be returned as a string.
168 if (typeof response
== 'string') {
169 response
= $.parseJSON(response
);
172 // Prior to invoking the response's commands, verify that they can be
173 // trusted by checking for a response header. See
174 // ajax_set_verification_header() for details.
175 // - Empty responses are harmless so can bypass verification. This avoids
176 // an alert message for server-generated no-op responses that skip Ajax
178 // - Ajax objects with trusted URLs (e.g., ones defined server-side via
179 // #ajax) can bypass header verification. This is especially useful for
180 // Ajax with multipart forms. Because IFRAME transport is used, the
181 // response headers cannot be accessed for verification.
182 if (response
!== null && !Drupal
.settings
.urlIsAjaxTrusted
[ajax
.url
]) {
183 if (xmlhttprequest
.getResponseHeader('X-Drupal-Ajax-Token') !== '1') {
184 var customMessage
= Drupal
.t("The response failed verification so will not be processed.");
185 return ajax
.error(xmlhttprequest
, ajax
.url
, customMessage
);
189 return ajax
.success(response
, status
);
191 complete: function (xmlhttprequest
, status
) {
192 ajax
.ajaxing
= false;
193 if (status
== 'error' || status
== 'parsererror') {
194 return ajax
.error(xmlhttprequest
, ajax
.url
);
201 // Bind the ajaxSubmit function to the element event.
202 $(ajax
.element
).bind(element_settings
.event
, function (event
) {
203 if (!Drupal
.settings
.urlIsAjaxTrusted
[ajax
.url
] && !Drupal
.urlIsLocal(ajax
.url
)) {
204 throw new Error(Drupal
.t('The callback URL is not local and not trusted: !url', {'!url': ajax
.url
}));
206 return ajax
.eventResponse(this, event
);
209 // If necessary, enable keyboard submission so that Ajax behaviors
210 // can be triggered through keyboard input as well as e.g. a mousedown
212 if (element_settings
.keypress
) {
213 $(ajax
.element
).keypress(function (event
) {
214 return ajax
.keypressResponse(this, event
);
218 // If necessary, prevent the browser default action of an additional event.
219 // For example, prevent the browser default action of a click, even if the
220 // AJAX behavior binds to mousedown.
221 if (element_settings
.prevent
) {
222 $(ajax
.element
).bind(element_settings
.prevent
, false);
227 * Handle a key press.
229 * The Ajax object will, if instructed, bind to a key press response. This
230 * will test to see if the key press is valid to trigger this event and
231 * if it is, trigger it for us and prevent other keypresses from triggering.
232 * In this case we're handling RETURN and SPACEBAR keypresses (event codes 13
233 * and 32. RETURN is often used to submit a form when in a textfield, and
234 * SPACE is often used to activate an element without submitting.
236 Drupal
.ajax
.prototype.keypressResponse = function (element
, event
) {
237 // Create a synonym for this to reduce code confusion.
240 // Detect enter key and space bar and allow the standard response for them,
241 // except for form elements of type 'text' and 'textarea', where the
242 // spacebar activation causes inappropriate activation if #ajax['keypress'] is
243 // TRUE. On a text-type widget a space should always be a space.
244 if (event
.which
== 13 || (event
.which
== 32 && element
.type
!= 'text' && element
.type
!= 'textarea')) {
245 $(ajax
.element_settings
.element
).trigger(ajax
.element_settings
.event
);
251 * Handle an event that triggers an Ajax response.
253 * When an event that triggers an Ajax response happens, this method will
254 * perform the actual Ajax call. It is bound to the event using
255 * bind() in the constructor, and it uses the options specified on the
258 Drupal
.ajax
.prototype.eventResponse = function (element
, event
) {
259 // Create a synonym for this to reduce code confusion.
262 // Do not perform another ajax command if one is already in progress.
269 // If setClick is set, we must set this to ensure that the button's
272 // Mark the clicked button. 'form.clk' is a special variable for
273 // ajaxSubmit that tells the system which element got clicked to
274 // trigger the submit. Without it there would be no 'op' or
276 element
.form
.clk
= element
;
279 ajax
.form
.ajaxSubmit(ajax
.options
);
282 ajax
.beforeSerialize(ajax
.element
, ajax
.options
);
283 $.ajax(ajax
.options
);
287 // Unset the ajax.ajaxing flag here because it won't be unset during
288 // the complete response.
289 ajax
.ajaxing
= false;
290 alert("An error occurred while attempting to process " + ajax
.options
.url
+ ": " + e
.message
);
293 // For radio/checkbox, allow the default event. On IE, this means letting
294 // it actually check the box.
295 if (typeof element
.type
!= 'undefined' && (element
.type
== 'checkbox' || element
.type
== 'radio')) {
305 * Handler for the form serialization.
307 * Runs before the beforeSend() handler (see below), and unlike that one, runs
308 * before field data is collected.
310 Drupal
.ajax
.prototype.beforeSerialize = function (element
, options
) {
311 // Allow detaching behaviors to update field values before collecting them.
312 // This is only needed when field values are added to the POST data, so only
313 // when there is a form such that this.form.ajaxSubmit() is used instead of
314 // $.ajax(). When there is no form and $.ajax() is used, beforeSerialize()
315 // isn't called, but don't rely on that: explicitly check this.form.
317 var settings
= this.settings
|| Drupal
.settings
;
318 Drupal
.detachBehaviors(this.form
, settings
, 'serialize');
321 // Prevent duplicate HTML ids in the returned markup.
322 // @see drupal_html_id()
323 options
.data
['ajax_html_ids[]'] = [];
324 $('[id]').each(function () {
325 options
.data
['ajax_html_ids[]'].push(this.id
);
328 // Allow Drupal to return new JavaScript and CSS files to load without
329 // returning the ones already loaded.
330 // @see ajax_base_page_theme()
331 // @see drupal_get_css()
332 // @see drupal_get_js()
333 options
.data
['ajax_page_state[theme]'] = Drupal
.settings
.ajaxPageState
.theme
;
334 options
.data
['ajax_page_state[theme_token]'] = Drupal
.settings
.ajaxPageState
.theme_token
;
335 for (var key
in Drupal
.settings
.ajaxPageState
.css
) {
336 options
.data
['ajax_page_state[css][' + key
+ ']'] = 1;
338 for (var key
in Drupal
.settings
.ajaxPageState
.js
) {
339 options
.data
['ajax_page_state[js][' + key
+ ']'] = 1;
344 * Modify form values prior to form submission.
346 Drupal
.ajax
.prototype.beforeSubmit = function (form_values
, element
, options
) {
347 // This function is left empty to make it simple to override for modules
348 // that wish to add functionality here.
352 * Prepare the Ajax request before it is sent.
354 Drupal
.ajax
.prototype.beforeSend = function (xmlhttprequest
, options
) {
355 // For forms without file inputs, the jQuery Form plugin serializes the form
356 // values, and then calls jQuery's $.ajax() function, which invokes this
357 // handler. In this circumstance, options.extraData is never used. For forms
358 // with file inputs, the jQuery Form plugin uses the browser's normal form
359 // submission mechanism, but captures the response in a hidden IFRAME. In this
360 // circumstance, it calls this handler first, and then appends hidden fields
361 // to the form to submit the values in options.extraData. There is no simple
362 // way to know which submission mechanism will be used, so we add to extraData
363 // regardless, and allow it to be ignored in the former case.
365 options
.extraData
= options
.extraData
|| {};
367 // Let the server know when the IFRAME submission mechanism is used. The
368 // server can use this information to wrap the JSON response in a TEXTAREA,
369 // as per http://jquery.malsup.com/form/#file-upload.
370 options
.extraData
.ajax_iframe_upload
= '1';
372 // The triggering element is about to be disabled (see below), but if it
373 // contains a value (e.g., a checkbox, textfield, select, etc.), ensure that
374 // value is included in the submission. As per above, submissions that use
375 // $.ajax() are already serialized prior to the element being disabled, so
376 // this is only needed for IFRAME submissions.
377 var v
= $.fieldValue(this.element
);
379 options
.extraData
[this.element
.name
] = Drupal
.checkPlain(v
);
383 // Disable the element that received the change to prevent user interface
384 // interaction while the Ajax request is in progress. ajax.ajaxing prevents
385 // the element from triggering a new request, but does not prevent the user
386 // from changing its value.
387 $(this.element
).addClass('progress-disabled').attr('disabled', true);
389 // Insert progressbar or throbber.
390 if (this.progress
.type
== 'bar') {
391 var progressBar
= new Drupal
.progressBar('ajax-progress-' + this.element
.id
, eval(this.progress
.update_callback
), this.progress
.method
, eval(this.progress
.error_callback
));
392 if (this.progress
.message
) {
393 progressBar
.setProgress(-1, this.progress
.message
);
395 if (this.progress
.url
) {
396 progressBar
.startMonitoring(this.progress
.url
, this.progress
.interval
|| 1500);
398 this.progress
.element
= $(progressBar
.element
).addClass('ajax-progress ajax-progress-bar');
399 this.progress
.object
= progressBar
;
400 $(this.element
).after(this.progress
.element
);
402 else if (this.progress
.type
== 'throbber') {
403 this.progress
.element
= $('<div class="ajax-progress ajax-progress-throbber"><div class="throbber"> </div></div>');
404 if (this.progress
.message
) {
405 $('.throbber', this.progress
.element
).after('<div class="message">' + this.progress
.message
+ '</div>');
407 $(this.element
).after(this.progress
.element
);
412 * Handler for the form redirection completion.
414 Drupal
.ajax
.prototype.success = function (response
, status
) {
415 // Remove the progress element.
416 if (this.progress
.element
) {
417 $(this.progress
.element
).remove();
419 if (this.progress
.object
) {
420 this.progress
.object
.stopMonitoring();
422 $(this.element
).removeClass('progress-disabled').removeAttr('disabled');
424 Drupal
.freezeHeight();
426 for (var i
in response
) {
427 if (response
.hasOwnProperty(i
) && response
[i
]['command'] && this.commands
[response
[i
]['command']]) {
428 this.commands
[response
[i
]['command']](this, response
[i
], status
);
432 // Reattach behaviors, if they were detached in beforeSerialize(). The
433 // attachBehaviors() called on the new content from processing the response
434 // commands is not sufficient, because behaviors from the entire form need
437 var settings
= this.settings
|| Drupal
.settings
;
438 Drupal
.attachBehaviors(this.form
, settings
);
441 Drupal
.unfreezeHeight();
443 // Remove any response-specific settings so they don't get used on the next
445 this.settings
= null;
449 * Build an effect object which tells us how to apply the effect when adding new HTML.
451 Drupal
.ajax
.prototype.getEffect = function (response
) {
452 var type
= response
.effect
|| this.effect
;
453 var speed
= response
.speed
|| this.speed
;
456 if (type
== 'none') {
457 effect
.showEffect
= 'show';
458 effect
.hideEffect
= 'hide';
459 effect
.showSpeed
= '';
461 else if (type
== 'fade') {
462 effect
.showEffect
= 'fadeIn';
463 effect
.hideEffect
= 'fadeOut';
464 effect
.showSpeed
= speed
;
467 effect
.showEffect
= type
+ 'Toggle';
468 effect
.hideEffect
= type
+ 'Toggle';
469 effect
.showSpeed
= speed
;
476 * Handler for the form redirection error.
478 Drupal
.ajax
.prototype.error = function (xmlhttprequest
, uri
, customMessage
) {
479 Drupal
.displayAjaxError(Drupal
.ajaxError(xmlhttprequest
, uri
, customMessage
));
480 // Remove the progress element.
481 if (this.progress
.element
) {
482 $(this.progress
.element
).remove();
484 if (this.progress
.object
) {
485 this.progress
.object
.stopMonitoring();
488 $(this.wrapper
).show();
489 // Re-enable the element.
490 $(this.element
).removeClass('progress-disabled').removeAttr('disabled');
491 // Reattach behaviors, if they were detached in beforeSerialize().
493 var settings
= this.settings
|| Drupal
.settings
;
494 Drupal
.attachBehaviors(this.form
, settings
);
499 * Provide a series of commands that the server can request the client perform.
501 Drupal
.ajax
.prototype.commands
= {
503 * Command to insert new content into the DOM.
505 insert: function (ajax
, response
, status
) {
506 // Get information from the response. If it is not there, default to
508 var wrapper
= response
.selector
? $(response
.selector
) : $(ajax
.wrapper
);
509 var method
= response
.method
|| ajax
.method
;
510 var effect
= ajax
.getEffect(response
);
512 // We don't know what response.data contains: it might be a string of text
513 // without HTML, so don't rely on jQuery correctly iterpreting
514 // $(response.data) as new HTML rather than a CSS selector. Also, if
515 // response.data contains top-level text nodes, they get lost with either
516 // $(response.data) or $('<div></div>').replaceWith(response.data).
517 var new_content_wrapped
= $('<div></div>').html(response
.data
);
518 var new_content
= new_content_wrapped
.contents();
520 // For legacy reasons, the effects processing code assumes that new_content
521 // consists of a single top-level element. Also, it has not been
522 // sufficiently tested whether attachBehaviors() can be successfully called
523 // with a context object that includes top-level text nodes. However, to
524 // give developers full control of the HTML appearing in the page, and to
525 // enable Ajax content to be inserted in places where DIV elements are not
526 // allowed (e.g., within TABLE, TR, and SPAN parents), we check if the new
527 // content satisfies the requirement of a single top-level element, and
528 // only use the container DIV created above when it doesn't. For more
529 // information, please see http://drupal.org/node/736066.
530 if (new_content
.length
!= 1 || new_content
.get(0).nodeType
!= 1) {
531 new_content
= new_content_wrapped
;
534 // If removing content from the wrapper, detach behaviors first.
541 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
542 Drupal
.detachBehaviors(wrapper
, settings
);
545 // Add the new content to the page.
546 wrapper
[method
](new_content
);
548 // Immediately hide the new content if we're using any effects.
549 if (effect
.showEffect
!= 'show') {
553 // Determine which effect to use and what content will receive the
554 // effect, then show the new content.
555 if ($('.ajax-new-content', new_content
).length
> 0) {
556 $('.ajax-new-content', new_content
).hide();
558 $('.ajax-new-content', new_content
)[effect
.showEffect
](effect
.showSpeed
);
560 else if (effect
.showEffect
!= 'show') {
561 new_content
[effect
.showEffect
](effect
.showSpeed
);
564 // Attach all JavaScript behaviors to the new content, if it was successfully
565 // added to the page, this if statement allows #ajax['wrapper'] to be
567 if (new_content
.parents('html').length
> 0) {
568 // Apply any settings from the returned JSON if available.
569 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
570 Drupal
.attachBehaviors(new_content
, settings
);
575 * Command to remove a chunk from the page.
577 remove: function (ajax
, response
, status
) {
578 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
579 Drupal
.detachBehaviors($(response
.selector
), settings
);
580 $(response
.selector
).remove();
584 * Command to mark a chunk changed.
586 changed: function (ajax
, response
, status
) {
587 if (!$(response
.selector
).hasClass('ajax-changed')) {
588 $(response
.selector
).addClass('ajax-changed');
589 if (response
.asterisk
) {
590 $(response
.selector
).find(response
.asterisk
).append(' <span class="ajax-changed">*</span> ');
596 * Command to provide an alert.
598 alert: function (ajax
, response
, status
) {
599 alert(response
.text
, response
.title
);
603 * Command to provide the jQuery css() function.
605 css: function (ajax
, response
, status
) {
606 $(response
.selector
).css(response
.argument
);
610 * Command to set the settings that will be used for other commands in this response.
612 settings: function (ajax
, response
, status
) {
613 if (response
.merge
) {
614 $.extend(true, Drupal
.settings
, response
.settings
);
617 ajax
.settings
= response
.settings
;
622 * Command to attach data using jQuery's data API.
624 data: function (ajax
, response
, status
) {
625 $(response
.selector
).data(response
.name
, response
.value
);
629 * Command to apply a jQuery method.
631 invoke: function (ajax
, response
, status
) {
632 var $element
= $(response
.selector
);
633 $element
[response
.method
].apply($element
, response
.arguments
);
637 * Command to restripe a table.
639 restripe: function (ajax
, response
, status
) {
640 // :even and :odd are reversed because jQuery counts from 0 and
641 // we count from 1, so we're out of sync.
642 // Match immediate children of the parent element to allow nesting.
643 $('> tbody > tr:visible, > tr:visible', $(response
.selector
))
644 .removeClass('odd even')
645 .filter(':even').addClass('odd').end()
646 .filter(':odd').addClass('even');
650 * Command to add css.
652 * Uses the proprietary addImport method if available as browsers which
653 * support that method ignore @import statements in dynamically added
656 add_css: function (ajax
, response
, status
) {
657 // Add the styles in the normal way.
658 $('head').prepend(response
.data
);
659 // Add imports in the styles using the addImport method if available.
660 var match
, importMatch
= /^@import url\("(.*)"\);$/igm;
661 if (document
.styleSheets
[0].addImport
&& importMatch
.test(response
.data
)) {
662 importMatch
.lastIndex
= 0;
663 while (match
= importMatch
.exec(response
.data
)) {
664 document
.styleSheets
[0].addImport(match
[1]);
670 * Command to update a form's build ID.
672 updateBuildId: function(ajax
, response
, status
) {
673 $('input[name="form_build_id"][value="' + response
['old'] + '"]').val(response
['new']);