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
|| {};
18 * Attaches the Ajax behavior to each Ajax form element.
20 Drupal
.behaviors
.AJAX
= {
21 attach: function (context
, settings
) {
22 // Load all Ajax behaviors specified in the settings.
23 for (var base
in settings
.ajax
) {
24 if (!$('#' + base
+ '.ajax-processed').length
) {
25 var element_settings
= settings
.ajax
[base
];
27 if (typeof element_settings
.selector
== 'undefined') {
28 element_settings
.selector
= '#' + base
;
30 $(element_settings
.selector
).each(function () {
31 element_settings
.element
= this;
32 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
35 $('#' + base
).addClass('ajax-processed');
39 // Bind Ajax behaviors to all items showing the class.
40 $('.use-ajax:not(.ajax-processed)').addClass('ajax-processed').each(function () {
41 var element_settings
= {};
42 // Clicked links look better with the throbber than the progress bar.
43 element_settings
.progress
= { 'type': 'throbber' };
45 // For anchor tags, these will go to the target of the anchor rather
46 // than the usual location.
47 if ($(this).attr('href')) {
48 element_settings
.url
= $(this).attr('href');
49 element_settings
.event
= 'click';
51 var base
= $(this).attr('id');
52 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
55 // This class means to submit the form to the action using Ajax.
56 $('.use-ajax-submit:not(.ajax-processed)').addClass('ajax-processed').each(function () {
57 var element_settings
= {};
59 // Ajax submits specified in this manner automatically submit to the
60 // normal form action.
61 element_settings
.url
= $(this.form
).attr('action');
62 // Form submit button clicks need to tell the form what was clicked so
63 // it gets passed in the POST request.
64 element_settings
.setClick
= true;
65 // Form buttons use the 'click' event rather than mousedown.
66 element_settings
.event
= 'click';
67 // Clicked form buttons look better with the throbber than the progress bar.
68 element_settings
.progress
= { 'type': 'throbber' };
70 var base
= $(this).attr('id');
71 Drupal
.ajax
[base
] = new Drupal
.ajax(base
, this, element_settings
);
79 * All Ajax objects on a page are accessible through the global Drupal.ajax
80 * object and are keyed by the submit button's ID. You can access them from
81 * your module's JavaScript file to override properties or functions.
83 * For example, if your Ajax enabled button has the ID 'edit-submit', you can
84 * redefine the function that is called to insert the new content like this
85 * (inside a Drupal.behaviors attach block):
87 * Drupal.behaviors.myCustomAJAXStuff = {
88 * attach: function (context, settings) {
89 * Drupal.ajax['edit-submit'].commands.insert = function (ajax, response, status) {
90 * new_content = $(response.data);
91 * $('#my-wrapper').append(new_content);
92 * alert('New content was appended to #my-wrapper');
98 Drupal
.ajax = function (base
, element
, element_settings
) {
103 selector
: '#' + base
,
106 method
: 'replaceWith',
109 message
: Drupal
.t('Please wait...')
116 $.extend(this, defaults
, element_settings
);
118 this.element
= element
;
119 this.element_settings
= element_settings
;
121 // Replacing 'nojs' with 'ajax' in the URL allows for an easy method to let
122 // the server detect when it needs to degrade gracefully.
123 // There are five scenarios to check for:
125 // 2. /nojs$ - The end of a URL string.
126 // 3. /nojs? - Followed by a query (with clean URLs enabled).
127 // E.g.: path/nojs?destination=foobar
128 // 4. /nojs& - Followed by a query (without clean URLs enabled).
129 // E.g.: ?q=path/nojs&destination=foobar
130 // 5. /nojs# - Followed by a fragment.
131 // E.g.: path/nojs#myfragment
132 this.url
= element_settings
.url
.replace(/\/nojs(\/|$|\?|&|#)/g, '/ajax$1');
133 this.wrapper
= '#' + element_settings
.wrapper
;
135 // If there isn't a form, jQuery.ajax() will be used instead, allowing us to
136 // bind Ajax to links as well.
137 if (this.element
.form
) {
138 this.form
= $(this.element
.form
);
141 // Set the options for the ajaxSubmit function.
142 // The 'this' variable will not persist inside of the options object.
147 beforeSerialize: function (element_settings
, options
) {
148 return ajax
.beforeSerialize(element_settings
, options
);
150 beforeSubmit: function (form_values
, element_settings
, options
) {
152 return ajax
.beforeSubmit(form_values
, element_settings
, options
);
154 beforeSend: function (xmlhttprequest
, options
) {
156 return ajax
.beforeSend(xmlhttprequest
, options
);
158 success: function (response
, status
) {
159 // Sanity check for browser support (object expected).
160 // When using iFrame uploads, responses must be returned as a string.
161 if (typeof response
== 'string') {
162 response
= $.parseJSON(response
);
164 return ajax
.success(response
, status
);
166 complete: function (response
, status
) {
167 ajax
.ajaxing
= false;
168 if (status
== 'error' || status
== 'parsererror') {
169 return ajax
.error(response
, ajax
.url
);
176 // Bind the ajaxSubmit function to the element event.
177 $(ajax
.element
).bind(element_settings
.event
, function (event
) {
178 return ajax
.eventResponse(this, event
);
181 // If necessary, enable keyboard submission so that Ajax behaviors
182 // can be triggered through keyboard input as well as e.g. a mousedown
184 if (element_settings
.keypress
) {
185 $(ajax
.element
).keypress(function (event
) {
186 return ajax
.keypressResponse(this, event
);
190 // If necessary, prevent the browser default action of an additional event.
191 // For example, prevent the browser default action of a click, even if the
192 // AJAX behavior binds to mousedown.
193 if (element_settings
.prevent
) {
194 $(ajax
.element
).bind(element_settings
.prevent
, false);
199 * Handle a key press.
201 * The Ajax object will, if instructed, bind to a key press response. This
202 * will test to see if the key press is valid to trigger this event and
203 * if it is, trigger it for us and prevent other keypresses from triggering.
204 * In this case we're handling RETURN and SPACEBAR keypresses (event codes 13
205 * and 32. RETURN is often used to submit a form when in a textfield, and
206 * SPACE is often used to activate an element without submitting.
208 Drupal
.ajax
.prototype.keypressResponse = function (element
, event
) {
209 // Create a synonym for this to reduce code confusion.
212 // Detect enter key and space bar and allow the standard response for them,
213 // except for form elements of type 'text' and 'textarea', where the
214 // spacebar activation causes inappropriate activation if #ajax['keypress'] is
215 // TRUE. On a text-type widget a space should always be a space.
216 if (event
.which
== 13 || (event
.which
== 32 && element
.type
!= 'text' && element
.type
!= 'textarea')) {
217 $(ajax
.element_settings
.element
).trigger(ajax
.element_settings
.event
);
223 * Handle an event that triggers an Ajax response.
225 * When an event that triggers an Ajax response happens, this method will
226 * perform the actual Ajax call. It is bound to the event using
227 * bind() in the constructor, and it uses the options specified on the
230 Drupal
.ajax
.prototype.eventResponse = function (element
, event
) {
231 // Create a synonym for this to reduce code confusion.
234 // Do not perform another ajax command if one is already in progress.
241 // If setClick is set, we must set this to ensure that the button's
244 // Mark the clicked button. 'form.clk' is a special variable for
245 // ajaxSubmit that tells the system which element got clicked to
246 // trigger the submit. Without it there would be no 'op' or
248 element
.form
.clk
= element
;
251 ajax
.form
.ajaxSubmit(ajax
.options
);
254 ajax
.beforeSerialize(ajax
.element
, ajax
.options
);
255 $.ajax(ajax
.options
);
259 // Unset the ajax.ajaxing flag here because it won't be unset during
260 // the complete response.
261 ajax
.ajaxing
= false;
262 alert("An error occurred while attempting to process " + ajax
.options
.url
+ ": " + e
.message
);
265 // For radio/checkbox, allow the default event. On IE, this means letting
266 // it actually check the box.
267 if (typeof element
.type
!= 'undefined' && (element
.type
== 'checkbox' || element
.type
== 'radio')) {
277 * Handler for the form serialization.
279 * Runs before the beforeSend() handler (see below), and unlike that one, runs
280 * before field data is collected.
282 Drupal
.ajax
.prototype.beforeSerialize = function (element
, options
) {
283 // Allow detaching behaviors to update field values before collecting them.
284 // This is only needed when field values are added to the POST data, so only
285 // when there is a form such that this.form.ajaxSubmit() is used instead of
286 // $.ajax(). When there is no form and $.ajax() is used, beforeSerialize()
287 // isn't called, but don't rely on that: explicitly check this.form.
289 var settings
= this.settings
|| Drupal
.settings
;
290 Drupal
.detachBehaviors(this.form
, settings
, 'serialize');
293 // Prevent duplicate HTML ids in the returned markup.
294 // @see drupal_html_id()
295 options
.data
['ajax_html_ids[]'] = [];
296 $('[id]').each(function () {
297 options
.data
['ajax_html_ids[]'].push(this.id
);
300 // Allow Drupal to return new JavaScript and CSS files to load without
301 // returning the ones already loaded.
302 // @see ajax_base_page_theme()
303 // @see drupal_get_css()
304 // @see drupal_get_js()
305 options
.data
['ajax_page_state[theme]'] = Drupal
.settings
.ajaxPageState
.theme
;
306 options
.data
['ajax_page_state[theme_token]'] = Drupal
.settings
.ajaxPageState
.theme_token
;
307 for (var key
in Drupal
.settings
.ajaxPageState
.css
) {
308 options
.data
['ajax_page_state[css][' + key
+ ']'] = 1;
310 for (var key
in Drupal
.settings
.ajaxPageState
.js
) {
311 options
.data
['ajax_page_state[js][' + key
+ ']'] = 1;
316 * Modify form values prior to form submission.
318 Drupal
.ajax
.prototype.beforeSubmit = function (form_values
, element
, options
) {
319 // This function is left empty to make it simple to override for modules
320 // that wish to add functionality here.
324 * Prepare the Ajax request before it is sent.
326 Drupal
.ajax
.prototype.beforeSend = function (xmlhttprequest
, options
) {
327 // For forms without file inputs, the jQuery Form plugin serializes the form
328 // values, and then calls jQuery's $.ajax() function, which invokes this
329 // handler. In this circumstance, options.extraData is never used. For forms
330 // with file inputs, the jQuery Form plugin uses the browser's normal form
331 // submission mechanism, but captures the response in a hidden IFRAME. In this
332 // circumstance, it calls this handler first, and then appends hidden fields
333 // to the form to submit the values in options.extraData. There is no simple
334 // way to know which submission mechanism will be used, so we add to extraData
335 // regardless, and allow it to be ignored in the former case.
337 options
.extraData
= options
.extraData
|| {};
339 // Let the server know when the IFRAME submission mechanism is used. The
340 // server can use this information to wrap the JSON response in a TEXTAREA,
341 // as per http://jquery.malsup.com/form/#file-upload.
342 options
.extraData
.ajax_iframe_upload
= '1';
344 // The triggering element is about to be disabled (see below), but if it
345 // contains a value (e.g., a checkbox, textfield, select, etc.), ensure that
346 // value is included in the submission. As per above, submissions that use
347 // $.ajax() are already serialized prior to the element being disabled, so
348 // this is only needed for IFRAME submissions.
349 var v
= $.fieldValue(this.element
);
351 options
.extraData
[this.element
.name
] = v
;
355 // Disable the element that received the change to prevent user interface
356 // interaction while the Ajax request is in progress. ajax.ajaxing prevents
357 // the element from triggering a new request, but does not prevent the user
358 // from changing its value.
359 $(this.element
).addClass('progress-disabled').attr('disabled', true);
361 // Insert progressbar or throbber.
362 if (this.progress
.type
== 'bar') {
363 var progressBar
= new Drupal
.progressBar('ajax-progress-' + this.element
.id
, eval(this.progress
.update_callback
), this.progress
.method
, eval(this.progress
.error_callback
));
364 if (this.progress
.message
) {
365 progressBar
.setProgress(-1, this.progress
.message
);
367 if (this.progress
.url
) {
368 progressBar
.startMonitoring(this.progress
.url
, this.progress
.interval
|| 1500);
370 this.progress
.element
= $(progressBar
.element
).addClass('ajax-progress ajax-progress-bar');
371 this.progress
.object
= progressBar
;
372 $(this.element
).after(this.progress
.element
);
374 else if (this.progress
.type
== 'throbber') {
375 this.progress
.element
= $('<div class="ajax-progress ajax-progress-throbber"><div class="throbber"> </div></div>');
376 if (this.progress
.message
) {
377 $('.throbber', this.progress
.element
).after('<div class="message">' + this.progress
.message
+ '</div>');
379 $(this.element
).after(this.progress
.element
);
384 * Handler for the form redirection completion.
386 Drupal
.ajax
.prototype.success = function (response
, status
) {
387 // Remove the progress element.
388 if (this.progress
.element
) {
389 $(this.progress
.element
).remove();
391 if (this.progress
.object
) {
392 this.progress
.object
.stopMonitoring();
394 $(this.element
).removeClass('progress-disabled').removeAttr('disabled');
396 Drupal
.freezeHeight();
398 for (var i
in response
) {
399 if (response
[i
]['command'] && this.commands
[response
[i
]['command']]) {
400 this.commands
[response
[i
]['command']](this, response
[i
], status
);
404 // Reattach behaviors, if they were detached in beforeSerialize(). The
405 // attachBehaviors() called on the new content from processing the response
406 // commands is not sufficient, because behaviors from the entire form need
409 var settings
= this.settings
|| Drupal
.settings
;
410 Drupal
.attachBehaviors(this.form
, settings
);
413 Drupal
.unfreezeHeight();
415 // Remove any response-specific settings so they don't get used on the next
417 this.settings
= null;
421 * Build an effect object which tells us how to apply the effect when adding new HTML.
423 Drupal
.ajax
.prototype.getEffect = function (response
) {
424 var type
= response
.effect
|| this.effect
;
425 var speed
= response
.speed
|| this.speed
;
428 if (type
== 'none') {
429 effect
.showEffect
= 'show';
430 effect
.hideEffect
= 'hide';
431 effect
.showSpeed
= '';
433 else if (type
== 'fade') {
434 effect
.showEffect
= 'fadeIn';
435 effect
.hideEffect
= 'fadeOut';
436 effect
.showSpeed
= speed
;
439 effect
.showEffect
= type
+ 'Toggle';
440 effect
.hideEffect
= type
+ 'Toggle';
441 effect
.showSpeed
= speed
;
448 * Handler for the form redirection error.
450 Drupal
.ajax
.prototype.error = function (response
, uri
) {
451 alert(Drupal
.ajaxError(response
, uri
));
452 // Remove the progress element.
453 if (this.progress
.element
) {
454 $(this.progress
.element
).remove();
456 if (this.progress
.object
) {
457 this.progress
.object
.stopMonitoring();
460 $(this.wrapper
).show();
461 // Re-enable the element.
462 $(this.element
).removeClass('progress-disabled').removeAttr('disabled');
463 // Reattach behaviors, if they were detached in beforeSerialize().
465 var settings
= response
.settings
|| this.settings
|| Drupal
.settings
;
466 Drupal
.attachBehaviors(this.form
, settings
);
471 * Provide a series of commands that the server can request the client perform.
473 Drupal
.ajax
.prototype.commands
= {
475 * Command to insert new content into the DOM.
477 insert: function (ajax
, response
, status
) {
478 // Get information from the response. If it is not there, default to
480 var wrapper
= response
.selector
? $(response
.selector
) : $(ajax
.wrapper
);
481 var method
= response
.method
|| ajax
.method
;
482 var effect
= ajax
.getEffect(response
);
484 // We don't know what response.data contains: it might be a string of text
485 // without HTML, so don't rely on jQuery correctly iterpreting
486 // $(response.data) as new HTML rather than a CSS selector. Also, if
487 // response.data contains top-level text nodes, they get lost with either
488 // $(response.data) or $('<div></div>').replaceWith(response.data).
489 var new_content_wrapped
= $('<div></div>').html(response
.data
);
490 var new_content
= new_content_wrapped
.contents();
492 // For legacy reasons, the effects processing code assumes that new_content
493 // consists of a single top-level element. Also, it has not been
494 // sufficiently tested whether attachBehaviors() can be successfully called
495 // with a context object that includes top-level text nodes. However, to
496 // give developers full control of the HTML appearing in the page, and to
497 // enable Ajax content to be inserted in places where DIV elements are not
498 // allowed (e.g., within TABLE, TR, and SPAN parents), we check if the new
499 // content satisfies the requirement of a single top-level element, and
500 // only use the container DIV created above when it doesn't. For more
501 // information, please see http://drupal.org/node/736066.
502 if (new_content
.length
!= 1 || new_content
.get(0).nodeType
!= 1) {
503 new_content
= new_content_wrapped
;
506 // If removing content from the wrapper, detach behaviors first.
513 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
514 Drupal
.detachBehaviors(wrapper
, settings
);
517 // Add the new content to the page.
518 wrapper
[method
](new_content
);
520 // Immediately hide the new content if we're using any effects.
521 if (effect
.showEffect
!= 'show') {
525 // Determine which effect to use and what content will receive the
526 // effect, then show the new content.
527 if ($('.ajax-new-content', new_content
).length
> 0) {
528 $('.ajax-new-content', new_content
).hide();
530 $('.ajax-new-content', new_content
)[effect
.showEffect
](effect
.showSpeed
);
532 else if (effect
.showEffect
!= 'show') {
533 new_content
[effect
.showEffect
](effect
.showSpeed
);
536 // Attach all JavaScript behaviors to the new content, if it was successfully
537 // added to the page, this if statement allows #ajax['wrapper'] to be
539 if (new_content
.parents('html').length
> 0) {
540 // Apply any settings from the returned JSON if available.
541 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
542 Drupal
.attachBehaviors(new_content
, settings
);
547 * Command to remove a chunk from the page.
549 remove: function (ajax
, response
, status
) {
550 var settings
= response
.settings
|| ajax
.settings
|| Drupal
.settings
;
551 Drupal
.detachBehaviors($(response
.selector
), settings
);
552 $(response
.selector
).remove();
556 * Command to mark a chunk changed.
558 changed: function (ajax
, response
, status
) {
559 if (!$(response
.selector
).hasClass('ajax-changed')) {
560 $(response
.selector
).addClass('ajax-changed');
561 if (response
.asterisk
) {
562 $(response
.selector
).find(response
.asterisk
).append(' <span class="ajax-changed">*</span> ');
568 * Command to provide an alert.
570 alert: function (ajax
, response
, status
) {
571 alert(response
.text
, response
.title
);
575 * Command to provide the jQuery css() function.
577 css: function (ajax
, response
, status
) {
578 $(response
.selector
).css(response
.argument
);
582 * Command to set the settings that will be used for other commands in this response.
584 settings: function (ajax
, response
, status
) {
585 if (response
.merge
) {
586 $.extend(true, Drupal
.settings
, response
.settings
);
589 ajax
.settings
= response
.settings
;
594 * Command to attach data using jQuery's data API.
596 data: function (ajax
, response
, status
) {
597 $(response
.selector
).data(response
.name
, response
.value
);
601 * Command to apply a jQuery method.
603 invoke: function (ajax
, response
, status
) {
604 var $element
= $(response
.selector
);
605 $element
[response
.method
].apply($element
, response
.arguments
);
609 * Command to restripe a table.
611 restripe: function (ajax
, response
, status
) {
612 // :even and :odd are reversed because jQuery counts from 0 and
613 // we count from 1, so we're out of sync.
614 // Match immediate children of the parent element to allow nesting.
615 $('> tbody > tr:visible, > tr:visible', $(response
.selector
))
616 .removeClass('odd even')
617 .filter(':even').addClass('odd').end()
618 .filter(':odd').addClass('even');