1 <?php

     2 

     3 /**

     4  * @file

     5  * Functions for use with Drupal's Ajax framework.

     6  */

     7 

     8 /**

     9  * @defgroup ajax Ajax framework

    10  * @{

    11  * Functions for Drupal's Ajax framework.

    12  *

    13  * Drupal's Ajax framework is used to dynamically update parts of a page's HTML

    14  * based on data from the server. Upon a specified event, such as a button

    15  * click, a callback function is triggered which performs server-side logic and

    16  * may return updated markup, which is then replaced on-the-fly with no page

    17  * refresh necessary.

    18  *

    19  * This framework creates a PHP macro language that allows the server to

    20  * instruct JavaScript to perform actions on the client browser. When using

    21  * forms, it can be used with the #ajax property.

    22  * The #ajax property can be used to bind events to the Ajax framework. By

    23  * default, #ajax uses 'system/ajax' as its path for submission and thus calls

    24  * ajax_form_callback() and a defined #ajax['callback'] function.

    25  * However, you may optionally specify a different path to request or a

    26  * different callback function to invoke, which can return updated HTML or can

    27  * also return a richer set of

    28  * @link ajax_commands Ajax framework commands @endlink.

    29  *

    30  * Standard form handling is as follows:

    31  *   - A form element has a #ajax property that includes #ajax['callback'] and

    32  *     omits #ajax['path']. See below about using #ajax['path'] to implement

    33  *     advanced use-cases that require something other than standard form

    34  *     handling.

    35  *   - On the specified element, Ajax processing is triggered by a change to

    36  *     that element.

    37  *   - The browser submits an HTTP POST request to the 'system/ajax' Drupal

    38  *     path.

    39  *   - The menu page callback for 'system/ajax', ajax_form_callback(), calls

    40  *     drupal_process_form() to process the form submission and rebuild the

    41  *     form if necessary. The form is processed in much the same way as if it

    42  *     were submitted without Ajax, with the same #process functions and

    43  *     validation and submission handlers called in either case, making it easy

    44  *     to create Ajax-enabled forms that degrade gracefully when JavaScript is

    45  *     disabled.

    46  *   - After form processing is complete, ajax_form_callback() calls the

    47  *     function named by #ajax['callback'], which returns the form element that

    48  *     has been updated and needs to be returned to the browser, or

    49  *     alternatively, an array of custom Ajax commands.

    50  *   - The page delivery callback for 'system/ajax', ajax_deliver(), renders the

    51  *     element returned by #ajax['callback'], and returns the JSON string

    52  *     created by ajax_render() to the browser.

    53  *   - The browser unserializes the returned JSON string into an array of

    54  *     command objects and executes each command, resulting in the old page

    55  *     content within and including the HTML element specified by

    56  *     #ajax['wrapper'] being replaced by the new content returned by

    57  *     #ajax['callback'], using a JavaScript animation effect specified by

    58  *     #ajax['effect'].

    59  *

    60  * A simple example of basic Ajax use from the

    61  * @link http://drupal.org/project/examples Examples module @endlink follows:

    62  * @code

    63  * function main_page() {

    64  *   return drupal_get_form('ajax_example_simplest');

    65  * }

    66  *

    67  * function ajax_example_simplest($form, &$form_state) {

    68  *   $form = array();

    69  *   $form['changethis'] = array(

    70  *     '#type' => 'select',

    71  *     '#options' => array(

    72  *       'one' => 'one',

    73  *       'two' => 'two',

    74  *       'three' => 'three',

    75  *     ),

    76  *     '#ajax' => array(

    77  *       'callback' => 'ajax_example_simplest_callback',

    78  *       'wrapper' => 'replace_textfield_div',

    79  *      ),

    80  *   );

    81 

    82  *   // This entire form element will be replaced with an updated value.

    83  *   $form['replace_textfield'] = array(

    84  *     '#type' => 'textfield',

    85  *     '#title' => t("The default value will be changed"),

    86  *     '#description' => t("Say something about why you chose") . "'" .

    87  *       (!empty($form_state['values']['changethis'])

    88  *       ? $form_state['values']['changethis'] : t("Not changed yet")) . "'",

    89  *     '#prefix' => '<div id="replace_textfield_div">',

    90  *     '#suffix' => '</div>',

    91  *   );

    92  *   return $form;

    93  * }

    94  *

    95  * function ajax_example_simplest_callback($form, $form_state) {

    96  *   // The form has already been submitted and updated. We can return the replaced

    97  *   // item as it is.

    98  *   return $form['replace_textfield'];

    99  * }

   100  * @endcode

   101  *

   102  * In the above example, the 'changethis' element is Ajax-enabled. The default

   103  * #ajax['event'] is 'change', so when the 'changethis' element changes,

   104  * an Ajax call is made. The form is submitted and reprocessed, and then the

   105  * callback is called. In this case, the form has been automatically

   106  * built changing $form['replace_textfield']['#description'], so the callback

   107  * just returns that part of the form.

   108  *

   109  * To implement Ajax handling in a form, add '#ajax' to the form

   110  * definition of a field. That field will trigger an Ajax event when it is

   111  * clicked (or changed, depending on the kind of field). #ajax supports

   112  * the following parameters (either 'path' or 'callback' is required at least):

   113  * - #ajax['callback']: The callback to invoke to handle the server side of the

   114  *   Ajax event, which will receive a $form and $form_state as arguments, and

   115  *   returns a renderable array (most often a form or form fragment), an HTML

   116  *   string, or an array of Ajax commands. If returning a renderable array or

   117  *   a string, the value will replace the original element named in

   118  *   #ajax['wrapper'], and

   119  *   theme_status_messages()

   120  *   will be prepended to that

   121  *   element. (If the status messages are not wanted, return an array

   122  *   of Ajax commands instead.)

   123  *   #ajax['wrapper']. If an array of Ajax commands is returned, it will be

   124  *   executed by the calling code.

   125  * - #ajax['path']: The menu path to use for the request. This is often omitted

   126  *   and the default is used. This path should map

   127  *   to a menu page callback that returns data using ajax_render(). Defaults to

   128  *   'system/ajax', which invokes ajax_form_callback(), eventually calling

   129  *   the function named in #ajax['callback']. If you use a custom

   130  *   path, you must set up the menu entry and handle the entire callback in your

   131  *   own code.

   132  * - #ajax['wrapper']: The CSS ID of the area to be replaced by the content

   133  *   returned by the #ajax['callback'] function. The content returned from

   134  *   the callback will replace the entire element named by #ajax['wrapper'].

   135  *   The wrapper is usually created using #prefix and #suffix properties in the

   136  *   form. Note that this is the wrapper ID, not a CSS selector. So to replace

   137  *   the element referred to by the CSS selector #some-selector on the page,

   138  *   use #ajax['wrapper'] = 'some-selector', not '#some-selector'.

   139  * - #ajax['effect']: The jQuery effect to use when placing the new HTML.

   140  *   Defaults to no effect. Valid options are 'none', 'slide', or 'fade'.

   141  * - #ajax['speed']: The effect speed to use. Defaults to 'slow'. May be

   142  *   'slow', 'fast' or a number in milliseconds which represents the length

   143  *   of time the effect should run.

   144  * - #ajax['event']: The JavaScript event to respond to. This is normally

   145  *   selected automatically for the type of form widget being used, and

   146  *   is only needed if you need to override the default behavior.

   147  * - #ajax['prevent']: A JavaScript event to prevent when 'event' is triggered.

   148  *   Defaults to 'click' for #ajax on #type 'submit', 'button', and

   149  *   'image_button'. Multiple events may be specified separated by spaces.

   150  *   For example, when binding #ajax behaviors to form buttons, pressing the

   151  *   ENTER key within a textfield triggers the 'click' event of the form's first

   152  *   submit button. Triggering Ajax in this situation leads to problems, like

   153  *   breaking autocomplete textfields. Because of that, Ajax behaviors are bound

   154  *   to the 'mousedown' event on form buttons by default. However, binding to

   155  *   'mousedown' rather than 'click' means that it is possible to trigger a

   156  *   click by pressing the mouse, holding the mouse button down until the Ajax

   157  *   request is complete and the button is re-enabled, and then releasing the

   158  *   mouse button. For this case, 'prevent' can be set to 'click', so an

   159  *   additional event handler is bound to prevent such a click from triggering a

   160  *   non-Ajax form submission. This also prevents a textfield's ENTER press

   161  *   triggering a button's non-Ajax form submission behavior.

   162  * - #ajax['method']: The jQuery method to use to place the new HTML.

   163  *   Defaults to 'replaceWith'. May be: 'replaceWith', 'append', 'prepend',

   164  *   'before', 'after', or 'html'. See the

   165  *   @link http://api.jquery.com/category/manipulation/ jQuery manipulators documentation @endlink

   166  *   for more information on these methods.

   167  * - #ajax['progress']: Choose either a throbber or progress bar that is

   168  *   displayed while awaiting a response from the callback, and add an optional

   169  *   message. Possible keys: 'type', 'message', 'url', 'interval'.

   170  *   More information is available in the

   171  *   @link forms_api_reference.html Form API Reference @endlink

   172  *

   173  * In addition to using Form API for doing in-form modification, Ajax may be

   174  * enabled by adding classes to buttons and links. By adding the 'use-ajax'

   175  * class to a link, the link will be loaded via an Ajax call. When using this

   176  * method, the href of the link can contain '/nojs/' as part of the path. When

   177  * the Ajax framework makes the request, it will convert this to '/ajax/'.

   178  * The server is then able to easily tell if this request was made through an

   179  * actual Ajax request or in a degraded state, and respond appropriately.

   180  *

   181  * Similarly, submit buttons can be given the class 'use-ajax-submit'. The

   182  * form will then be submitted via Ajax to the path specified in the #action.

   183  * Like the ajax-submit class above, this path will have '/nojs/' replaced with

   184  * '/ajax/' so that the submit handler can tell if the form was submitted

   185  * in a degraded state or not.

   186  *

   187  * When responding to Ajax requests, the server should do what it needs to do

   188  * for that request, then create a commands array. This commands array will

   189  * be converted to a JSON object and returned to the client, which will then

   190  * iterate over the array and process it like a macro language.

   191  *

   192  * Each command item is an associative array which will be converted to a

   193  * command object on the JavaScript side. $command_item['command'] is the type

   194  * of command, e.g. 'alert' or 'replace', and will correspond to a method in the

   195  * Drupal.ajax[command] space. The command array may contain any other data that

   196  * the command needs to process, e.g. 'method', 'selector', 'settings', etc.

   197  *

   198  * Commands are usually created with a couple of helper functions, so they

   199  * look like this:

   200  * @code

   201  *   $commands = array();

   202  *   // Replace the content of '#object-1' on the page with 'some html here'.

   203  *   $commands[] = ajax_command_replace('#object-1', 'some html here');

   204  *   // Add a visual "changed" marker to the '#object-1' element.

   205  *   $commands[] = ajax_command_changed('#object-1');

   206  *   // Menu 'page callback' and #ajax['callback'] functions are supposed to

   207  *   // return render arrays. If returning an Ajax commands array, it must be

   208  *   // encapsulated in a render array structure.

   209  *   return array('#type' => 'ajax', '#commands' => $commands);

   210  * @endcode

   211  *

   212  * When returning an Ajax command array, it is often useful to have

   213  * status messages rendered along with other tasks in the command array.

   214  * In that case the Ajax commands array may be constructed like this:

   215  * @code

   216  *   $commands = array();

   217  *   $commands[] = ajax_command_replace(NULL, $output);

   218  *   $commands[] = ajax_command_prepend(NULL, theme('status_messages'));

   219  *   return array('#type' => 'ajax', '#commands' => $commands);

   220  * @endcode

   221  *

   222  * See @link ajax_commands Ajax framework commands @endlink

   223  */

   224 

   225 /**

   226  * Renders a commands array into JSON.

   227  *

   228  * @param $commands

   229  *   A list of macro commands generated by the use of ajax_command_*()

   230  *   functions.

   231  */

   232 function ajax_render($commands = array()) {

   233   // Although ajax_deliver() does this, some contributed and custom modules

   234   // render Ajax responses without using that delivery callback.

   235   ajax_set_verification_header();

   236 

   237   // Ajax responses aren't rendered with html.tpl.php, so we have to call

   238   // drupal_get_css() and drupal_get_js() here, in order to have new files added

   239   // during this request to be loaded by the page. We only want to send back

   240   // files that the page hasn't already loaded, so we implement simple diffing

   241   // logic using array_diff_key().

   242   foreach (array('css', 'js') as $type) {

   243     // It is highly suspicious if $_POST['ajax_page_state'][$type] is empty,

   244     // since the base page ought to have at least one JS file and one CSS file

   245     // loaded. It probably indicates an error, and rather than making the page

   246     // reload all of the files, instead we return no new files.

   247     if (empty($_POST['ajax_page_state'][$type])) {

   248       $items[$type] = array();

   249     }

   250     else {

   251       $function = 'drupal_add_' . $type;

   252       $items[$type] = $function();

   253       drupal_alter($type, $items[$type]);

   254       // @todo Inline CSS and JS items are indexed numerically. These can't be

   255       //   reliably diffed with array_diff_key(), since the number can change

   256       //   due to factors unrelated to the inline content, so for now, we strip

   257       //   the inline items from Ajax responses, and can add support for them

   258       //   when drupal_add_css() and drupal_add_js() are changed to use a hash

   259       //   of the inline content as the array key.

   260       foreach ($items[$type] as $key => $item) {

   261         if (is_numeric($key)) {

   262           unset($items[$type][$key]);

   263         }

   264       }

   265       // Ensure that the page doesn't reload what it already has.

   266       $items[$type] = array_diff_key($items[$type], $_POST['ajax_page_state'][$type]);

   267     }

   268   }

   269 

   270   // Render the HTML to load these files, and add AJAX commands to insert this

   271   // HTML in the page. We pass TRUE as the $skip_alter argument to prevent the

   272   // data from being altered again, as we already altered it above. Settings are

   273   // handled separately, afterwards.

   274   if (isset($items['js']['settings'])) {

   275     unset($items['js']['settings']);

   276   }

   277   $styles = drupal_get_css($items['css'], TRUE);

   278   $scripts_footer = drupal_get_js('footer', $items['js'], TRUE);

   279   $scripts_header = drupal_get_js('header', $items['js'], TRUE);

   280 

   281   $extra_commands = array();

   282   if (!empty($styles)) {

   283     $extra_commands[] = ajax_command_add_css($styles);

   284   }

   285   if (!empty($scripts_header)) {

   286     $extra_commands[] = ajax_command_prepend('head', $scripts_header);

   287   }

   288   if (!empty($scripts_footer)) {

   289     $extra_commands[] = ajax_command_append('body', $scripts_footer);

   290   }

   291   if (!empty($extra_commands)) {

   292     $commands = array_merge($extra_commands, $commands);

   293   }

   294 

   295   // Now add a command to merge changes and additions to Drupal.settings.

   296   $scripts = drupal_add_js();

   297   if (!empty($scripts['settings'])) {

   298     $settings = $scripts['settings'];

   299     array_unshift($commands, ajax_command_settings(drupal_array_merge_deep_array($settings['data']), TRUE));

   300   }

   301 

   302   // Allow modules to alter any Ajax response.

   303   drupal_alter('ajax_render', $commands);

   304 

   305   return drupal_json_encode($commands);

   306 }

   307 

   308 /**

   309  * Gets a form submitted via #ajax during an Ajax callback.

   310  *

   311  * This will load a form from the form cache used during Ajax operations. It

   312  * pulls the form info from $_POST.

   313  *

   314  * @return

   315  *   An array containing the $form, $form_state, $form_id, $form_build_id and an

   316  *   initial list of Ajax $commands. Use the list() function to break these

   317  *   apart:

   318  *   @code

   319  *     list($form, $form_state, $form_id, $form_build_id, $commands) = ajax_get_form();

   320  *   @endcode

   321  */

   322 function ajax_get_form() {

   323   $form_state = form_state_defaults();

   324 

   325   $form_build_id = $_POST['form_build_id'];

   326 

   327   // Get the form from the cache.

   328   $form = form_get_cache($form_build_id, $form_state);

   329   if (!$form) {

   330     // If $form cannot be loaded from the cache, the form_build_id in $_POST

   331     // must be invalid, which means that someone performed a POST request onto

   332     // system/ajax without actually viewing the concerned form in the browser.

   333     // This is likely a hacking attempt as it never happens under normal

   334     // circumstances, so we just do nothing.

   335     watchdog('ajax', 'Invalid form POST data.', array(), WATCHDOG_WARNING);

   336     drupal_exit();

   337   }

   338 

   339   // When a page level cache is enabled, the form-build id might have been

   340   // replaced from within form_get_cache. If this is the case, it is also

   341   // necessary to update it in the browser by issuing an appropriate Ajax

   342   // command.

   343   $commands = array();

   344   if (isset($form['#build_id_old']) && $form['#build_id_old'] != $form['#build_id']) {

   345     // If the form build ID has changed, issue an Ajax command to update it.

   346     $commands[] = ajax_command_update_build_id($form);

   347     $form_build_id = $form['#build_id'];

   348   }

   349 

   350   // Since some of the submit handlers are run, redirects need to be disabled.

   351   $form_state['no_redirect'] = TRUE;

   352 

   353   // When a form is rebuilt after Ajax processing, its #build_id and #action

   354   // should not change.

   355   // @see drupal_rebuild_form()

   356   $form_state['rebuild_info']['copy']['#build_id'] = TRUE;

   357   $form_state['rebuild_info']['copy']['#action'] = TRUE;

   358 

   359   // The form needs to be processed; prepare for that by setting a few internal

   360   // variables.

   361   $form_state['input'] = $_POST;

   362   $form_id = $form['#form_id'];

   363 

   364   return array($form, $form_state, $form_id, $form_build_id, $commands);

   365 }

   366 

   367 /**

   368  * Menu callback; handles Ajax requests for the #ajax Form API property.

   369  *

   370  * This rebuilds the form from cache and invokes the defined #ajax['callback']

   371  * to return an Ajax command structure for JavaScript. In case no 'callback' has

   372  * been defined, nothing will happen.

   373  *

   374  * The Form API #ajax property can be set both for buttons and other input

   375  * elements.

   376  *

   377  * This function is also the canonical example of how to implement

   378  * #ajax['path']. If processing is required that cannot be accomplished with

   379  * a callback, re-implement this function and set #ajax['path'] to the

   380  * enhanced function.

   381  *

   382  * @see system_menu()

   383  */

   384 function ajax_form_callback() {

   385   list($form, $form_state, $form_id, $form_build_id, $commands) = ajax_get_form();

   386   drupal_process_form($form['#form_id'], $form, $form_state);

   387 

   388   // We need to return the part of the form (or some other content) that needs

   389   // to be re-rendered so the browser can update the page with changed content.

   390   // Since this is the generic menu callback used by many Ajax elements, it is

   391   // up to the #ajax['callback'] function of the element (may or may not be a

   392   // button) that triggered the Ajax request to determine what needs to be

   393   // rendered.

   394   if (!empty($form_state['triggering_element'])) {

   395     $callback = $form_state['triggering_element']['#ajax']['callback'];

   396   }

   397   if (!empty($callback) && is_callable($callback)) {

   398     $result = $callback($form, $form_state);

   399 

   400     if (!(is_array($result) && isset($result['#type']) && $result['#type'] == 'ajax')) {

   401       // Turn the response into a #type=ajax array if it isn't one already.

   402       $result = array(

   403         '#type' => 'ajax',

   404         '#commands' => ajax_prepare_response($result),

   405       );

   406     }

   407 

   408     $result['#commands'] = array_merge($commands, $result['#commands']);

   409 

   410     return $result;

   411   }

   412 }

   413 

   414 /**

   415  * Theme callback for Ajax requests.

   416  *

   417  * Many different pages can invoke an Ajax request to system/ajax or another

   418  * generic Ajax path. It is almost always desired for an Ajax response to be

   419  * rendered using the same theme as the base page, because most themes are built

   420  * with the assumption that they control the entire page, so if the CSS for two

   421  * themes are both loaded for a given page, they may conflict with each other.

   422  * For example, Bartik is Drupal's default theme, and Seven is Drupal's default

   423  * administration theme. Depending on whether the "Use the administration theme

   424  * when editing or creating content" checkbox is checked, the node edit form may

   425  * be displayed in either theme, but the Ajax response to the Field module's

   426  * "Add another item" button should be rendered using the same theme as the rest

   427  * of the page. Therefore, system_menu() sets the 'theme callback' for

   428  * 'system/ajax' to this function, and it is recommended that modules

   429  * implementing other generic Ajax paths do the same.

   430  *

   431  * @see system_menu()

   432  * @see file_menu()

   433  */

   434 function ajax_base_page_theme() {

   435   if (!empty($_POST['ajax_page_state']['theme']) && !empty($_POST['ajax_page_state']['theme_token'])) {

   436     $theme = $_POST['ajax_page_state']['theme'];

   437     $token = $_POST['ajax_page_state']['theme_token'];

   438 

   439     // Prevent a request forgery from giving a person access to a theme they

   440     // shouldn't be otherwise allowed to see. However, since everyone is allowed

   441     // to see the default theme, token validation isn't required for that, and

   442     // bypassing it allows most use-cases to work even when accessed from the

   443     // page cache.

   444     if ($theme === variable_get('theme_default', 'bartik') || drupal_valid_token($token, $theme)) {

   445       return $theme;

   446     }

   447   }

   448 }

   449 

   450 /**

   451  * Packages and sends the result of a page callback as an Ajax response.

   452  *

   453  * This function is the equivalent of drupal_deliver_html_page(), but for Ajax

   454  * requests. Like that function, it:

   455  * - Adds needed HTTP headers.

   456  * - Prints rendered output.

   457  * - Performs end-of-request tasks.

   458  *

   459  * @param $page_callback_result

   460  *   The result of a page callback. Can be one of:

   461  *   - NULL: to indicate no content.

   462  *   - An integer menu status constant: to indicate an error condition.

   463  *   - A string of HTML content.

   464  *   - A renderable array of content.

   465  *

   466  * @see drupal_deliver_html_page()

   467  */

   468 function ajax_deliver($page_callback_result) {

   469   // Browsers do not allow JavaScript to read the contents of a user's local

   470   // files. To work around that, the jQuery Form plugin submits forms containing

   471   // a file input element to an IFRAME, instead of using XHR. Browsers do not

   472   // normally expect JSON strings as content within an IFRAME, so the response

   473   // must be customized accordingly.

   474   // @see http://malsup.com/jquery/form/#file-upload

   475   // @see Drupal.ajax.prototype.beforeSend()

   476   $iframe_upload = !empty($_POST['ajax_iframe_upload']);

   477 

   478   // Emit a Content-Type HTTP header if none has been added by the page callback

   479   // or by a wrapping delivery callback.

   480   if (is_null(drupal_get_http_header('Content-Type'))) {

   481     if (!$iframe_upload) {

   482       // Standard JSON can be returned to a browser's XHR object, and to

   483       // non-browser user agents.

   484       // @see http://www.ietf.org/rfc/rfc4627.txt?number=4627

   485       drupal_add_http_header('Content-Type', 'application/json; charset=utf-8');

   486     }

   487     else {

   488       // Browser IFRAMEs expect HTML. With most other content types, Internet

   489       // Explorer presents the user with a download prompt.

   490       drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');

   491     }

   492   }

   493 

   494   // Let ajax.js know that this response is safe to process.

   495   ajax_set_verification_header();

   496 

   497   // Print the response.

   498   $commands = ajax_prepare_response($page_callback_result);

   499   $json = ajax_render($commands);

   500   if (!$iframe_upload) {

   501     // Standard JSON can be returned to a browser's XHR object, and to

   502     // non-browser user agents.

   503     print $json;

   504   }

   505   else {

   506     // Browser IFRAMEs expect HTML. Browser extensions, such as Linkification

   507     // and Skype's Browser Highlighter, convert URLs, phone numbers, etc. into

   508     // links. This corrupts the JSON response. Protect the integrity of the

   509     // JSON data by making it the value of a textarea.

   510     // @see http://malsup.com/jquery/form/#file-upload

   511     // @see http://drupal.org/node/1009382

   512     print '<textarea>' . $json . '</textarea>';

   513   }

   514 

   515   // Perform end-of-request tasks.

   516   ajax_footer();

   517 }

   518 

   519 /**

   520  * Converts the return value of a page callback into an Ajax commands array.

   521  *

   522  * @param $page_callback_result

   523  *   The result of a page callback. Can be one of:

   524  *   - NULL: to indicate no content.

   525  *   - An integer menu status constant: to indicate an error condition.

   526  *   - A string of HTML content.

   527  *   - A renderable array of content.

   528  *

   529  * @return

   530  *   An Ajax commands array that can be passed to ajax_render().

   531  */

   532 function ajax_prepare_response($page_callback_result) {

   533   $commands = array();

   534   if (!isset($page_callback_result)) {

   535     // Simply delivering an empty commands array is sufficient. This results

   536     // in the Ajax request being completed, but nothing being done to the page.

   537   }

   538   elseif (is_int($page_callback_result)) {

   539     switch ($page_callback_result) {

   540       case MENU_NOT_FOUND:

   541         $commands[] = ajax_command_alert(t('The requested page could not be found.'));

   542         break;

   543 

   544       case MENU_ACCESS_DENIED:

   545         $commands[] = ajax_command_alert(t('You are not authorized to access this page.'));

   546         break;

   547 

   548       case MENU_SITE_OFFLINE:

   549         $commands[] = ajax_command_alert(filter_xss_admin(variable_get('maintenance_mode_message',

   550           t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal'))))));

   551         break;

   552     }

   553   }

   554   elseif (is_array($page_callback_result) && isset($page_callback_result['#type']) && ($page_callback_result['#type'] == 'ajax')) {

   555     // Complex Ajax callbacks can return a result that contains an error message

   556     // or a specific set of commands to send to the browser.

   557     $page_callback_result += element_info('ajax');

   558     $error = $page_callback_result['#error'];

   559     if (isset($error) && $error !== FALSE) {

   560       if ((empty($error) || $error === TRUE)) {

   561         $error = t('An error occurred while handling the request: The server received invalid input.');

   562       }

   563       $commands[] = ajax_command_alert($error);

   564     }

   565     else {

   566       $commands = $page_callback_result['#commands'];

   567     }

   568   }

   569   else {

   570     // Like normal page callbacks, simple Ajax callbacks can return HTML

   571     // content, as a string or render array. This HTML is inserted in some

   572     // relationship to #ajax['wrapper'], as determined by which jQuery DOM

   573     // manipulation method is used. The method used is specified by

   574     // #ajax['method']. The default method is 'replaceWith', which completely

   575     // replaces the old wrapper element and its content with the new HTML.

   576     $html = is_string($page_callback_result) ? $page_callback_result : drupal_render($page_callback_result);

   577     $commands[] = ajax_command_insert(NULL, $html);

   578     // Add the status messages inside the new content's wrapper element, so that

   579     // on subsequent Ajax requests, it is treated as old content.

   580     $commands[] = ajax_command_prepend(NULL, theme('status_messages'));

   581   }

   582 

   583   return $commands;

   584 }

   585 

   586 /**

   587  * Sets a response header for ajax.js to trust the response body.

   588  *

   589  * It is not safe to invoke Ajax commands within user-uploaded files, so this

   590  * header protects against those being invoked.

   591  *

   592  * @see Drupal.ajax.options.success()

   593  */

   594 function ajax_set_verification_header() {

   595   $added = &drupal_static(__FUNCTION__);

   596 

   597   // User-uploaded files cannot set any response headers, so a custom header is

   598   // used to indicate to ajax.js that this response is safe. Note that most

   599   // Ajax requests bound using the Form API will be protected by having the URL

   600   // flagged as trusted in Drupal.settings, so this header is used only for

   601   // things like custom markup that gets Ajax behaviors attached.

   602   if (empty($added)) {

   603     drupal_add_http_header('X-Drupal-Ajax-Token', '1');

   604     // Avoid sending the header twice.

   605     $added = TRUE;

   606   }

   607 }

   608 

   609 /**

   610  * Performs end-of-Ajax-request tasks.

   611  *

   612  * This function is the equivalent of drupal_page_footer(), but for Ajax

   613  * requests.

   614  *

   615  * @see drupal_page_footer()

   616  */

   617 function ajax_footer() {

   618   // Even for Ajax requests, invoke hook_exit() implementations. There may be

   619   // modules that need very fast Ajax responses, and therefore, run Ajax

   620   // requests with an early bootstrap.

   621   if (drupal_get_bootstrap_phase() == DRUPAL_BOOTSTRAP_FULL && (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update')) {

   622     module_invoke_all('exit');

   623   }

   624 

   625   // Commit the user session. See above comment about the possibility of this

   626   // function running without session.inc loaded.

   627   if (function_exists('drupal_session_commit')) {

   628     drupal_session_commit();

   629   }

   630 }

   631 

   632 /**

   633  * Form element processing handler for the #ajax form property.

   634  *

   635  * @param $element

   636  *   An associative array containing the properties of the element.

   637  *

   638  * @return

   639  *   The processed element.

   640  *

   641  * @see ajax_pre_render_element()

   642  */

   643 function ajax_process_form($element, &$form_state) {

   644   $element = ajax_pre_render_element($element);

   645   if (!empty($element['#ajax_processed'])) {

   646     $form_state['cache'] = TRUE;

   647   }

   648   return $element;

   649 }

   650 

   651 /**

   652  * Adds Ajax information about an element to communicate with JavaScript.

   653  *

   654  * If #ajax['path'] is set on an element, this additional JavaScript is added

   655  * to the page header to attach the Ajax behaviors. See ajax.js for more

   656  * information.

   657  *

   658  * @param $element

   659  *   An associative array containing the properties of the element.

   660  *   Properties used:

   661  *   - #ajax['event']

   662  *   - #ajax['prevent']

   663  *   - #ajax['path']

   664  *   - #ajax['options']

   665  *   - #ajax['wrapper']

   666  *   - #ajax['parameters']

   667  *   - #ajax['effect']

   668  *

   669  * @return

   670  *   The processed element with the necessary JavaScript attached to it.

   671  */

   672 function ajax_pre_render_element($element) {

   673   // Skip already processed elements.

   674   if (isset($element['#ajax_processed'])) {

   675     return $element;

   676   }

   677   // Initialize #ajax_processed, so we do not process this element again.

   678   $element['#ajax_processed'] = FALSE;

   679 

   680   // Nothing to do if there is neither a callback nor a path.

   681   if (!(isset($element['#ajax']['callback']) || isset($element['#ajax']['path']))) {

   682     return $element;

   683   }

   684 

   685   // Add a reasonable default event handler if none was specified.

   686   if (isset($element['#ajax']) && !isset($element['#ajax']['event'])) {

   687     switch ($element['#type']) {

   688       case 'submit':

   689       case 'button':

   690       case 'image_button':

   691         // Pressing the ENTER key within a textfield triggers the click event of

   692         // the form's first submit button. Triggering Ajax in this situation

   693         // leads to problems, like breaking autocomplete textfields, so we bind

   694         // to mousedown instead of click.

   695         // @see http://drupal.org/node/216059

   696         $element['#ajax']['event'] = 'mousedown';

   697         // Retain keyboard accessibility by setting 'keypress'. This causes

   698         // ajax.js to trigger 'event' when SPACE or ENTER are pressed while the

   699         // button has focus.

   700         $element['#ajax']['keypress'] = TRUE;

   701         // Binding to mousedown rather than click means that it is possible to

   702         // trigger a click by pressing the mouse, holding the mouse button down

   703         // until the Ajax request is complete and the button is re-enabled, and

   704         // then releasing the mouse button. Set 'prevent' so that ajax.js binds

   705         // an additional handler to prevent such a click from triggering a

   706         // non-Ajax form submission. This also prevents a textfield's ENTER

   707         // press triggering this button's non-Ajax form submission behavior.

   708         if (!isset($element['#ajax']['prevent'])) {

   709           $element['#ajax']['prevent'] = 'click';

   710         }

   711         break;

   712 

   713       case 'password':

   714       case 'textfield':

   715       case 'textarea':

   716         $element['#ajax']['event'] = 'blur';

   717         break;

   718 

   719       case 'radio':

   720       case 'checkbox':

   721       case 'select':

   722         $element['#ajax']['event'] = 'change';

   723         break;

   724 

   725       case 'link':

   726         $element['#ajax']['event'] = 'click';

   727         break;

   728 

   729       default:

   730         return $element;

   731     }

   732   }

   733 

   734   // Attach JavaScript settings to the element.

   735   if (isset($element['#ajax']['event'])) {

   736     $element['#attached']['library'][] = array('system', 'jquery.form');

   737     $element['#attached']['library'][] = array('system', 'drupal.ajax');

   738 

   739     $settings = $element['#ajax'];

   740 

   741     // Assign default settings.

   742     $settings += array(

   743       'path' => 'system/ajax',

   744       'options' => array(),

   745     );

   746 

   747     // @todo Legacy support. Remove in Drupal 8.

   748     if (isset($settings['method']) && $settings['method'] == 'replace') {

   749       $settings['method'] = 'replaceWith';

   750     }

   751 

   752     // Change path to URL.

   753     $settings['url'] = url($settings['path'], $settings['options']);

   754     unset($settings['path'], $settings['options']);

   755 

   756     // Add special data to $settings['submit'] so that when this element

   757     // triggers an Ajax submission, Drupal's form processing can determine which

   758     // element triggered it.

   759     // @see _form_element_triggered_scripted_submission()

   760     if (isset($settings['trigger_as'])) {

   761       // An element can add a 'trigger_as' key within #ajax to make the element

   762       // submit as though another one (for example, a non-button can use this

   763       // to submit the form as though a button were clicked). When using this,

   764       // the 'name' key is always required to identify the element to trigger

   765       // as. The 'value' key is optional, and only needed when multiple elements

   766       // share the same name, which is commonly the case for buttons.

   767       $settings['submit']['_triggering_element_name'] = $settings['trigger_as']['name'];

   768       if (isset($settings['trigger_as']['value'])) {

   769         $settings['submit']['_triggering_element_value'] = $settings['trigger_as']['value'];

   770       }

   771       unset($settings['trigger_as']);

   772     }

   773     elseif (isset($element['#name'])) {

   774       // Most of the time, elements can submit as themselves, in which case the

   775       // 'trigger_as' key isn't needed, and the element's name is used.

   776       $settings['submit']['_triggering_element_name'] = $element['#name'];

   777       // If the element is a (non-image) button, its name may not identify it

   778       // uniquely, in which case a match on value is also needed.

   779       // @see _form_button_was_clicked()

   780       if (isset($element['#button_type']) && empty($element['#has_garbage_value'])) {

   781         $settings['submit']['_triggering_element_value'] = $element['#value'];

   782       }

   783     }

   784 

   785     // Convert a simple #ajax['progress'] string into an array.

   786     if (isset($settings['progress']) && is_string($settings['progress'])) {

   787       $settings['progress'] = array('type' => $settings['progress']);

   788     }

   789     // Change progress path to a full URL.

   790     if (isset($settings['progress']['path'])) {

   791       $settings['progress']['url'] = url($settings['progress']['path']);

   792       unset($settings['progress']['path']);

   793     }

   794 

   795     $element['#attached']['js'][] = array(

   796       'type' => 'setting',

   797       'data' => array(

   798         'ajax' => array($element['#id'] => $settings),

   799         'urlIsAjaxTrusted' => array(

   800           $settings['url'] => TRUE,

   801         ),

   802       ),

   803     );

   804 

   805     // Indicate that Ajax processing was successful.

   806     $element['#ajax_processed'] = TRUE;

   807   }

   808   return $element;

   809 }

   810 

   811 /**

   812  * @} End of "defgroup ajax".

   813  */

   814 

   815 /**

   816  * @defgroup ajax_commands Ajax framework commands

   817  * @{

   818  * Functions to create various Ajax commands.

   819  *

   820  * These functions can be used to create arrays for use with the

   821  * ajax_render() function.

   822  */

   823 

   824 /**

   825  * Creates a Drupal Ajax 'alert' command.

   826  *

   827  * The 'alert' command instructs the client to display a JavaScript alert

   828  * dialog box.

   829  *

   830  * This command is implemented by Drupal.ajax.prototype.commands.alert()

   831  * defined in misc/ajax.js.

   832  *

   833  * @param $text

   834  *   The message string to display to the user.

   835  *

   836  * @return

   837  *   An array suitable for use with the ajax_render() function.

   838  */

   839 function ajax_command_alert($text) {

   840   return array(

   841     'command' => 'alert',

   842     'text' => $text,

   843   );

   844 }

   845 

   846 /**

   847  * Creates a Drupal Ajax 'insert' command using the method in #ajax['method'].

   848  *

   849  * This command instructs the client to insert the given HTML using whichever

   850  * jQuery DOM manipulation method has been specified in the #ajax['method']

   851  * variable of the element that triggered the request.

   852  *

   853  * This command is implemented by Drupal.ajax.prototype.commands.insert()

   854  * defined in misc/ajax.js.

   855  *

   856  * @param $selector

   857  *   A jQuery selector string. If the command is a response to a request from

   858  *   an #ajax form element then this value can be NULL.

   859  * @param $html

   860  *   The data to use with the jQuery method.

   861  * @param $settings

   862  *   An optional array of settings that will be used for this command only.

   863  *

   864  * @return

   865  *   An array suitable for use with the ajax_render() function.

   866  */

   867 function ajax_command_insert($selector, $html, $settings = NULL) {

   868   return array(

   869     'command' => 'insert',

   870     'method' => NULL,

   871     'selector' => $selector,

   872     'data' => $html,

   873     'settings' => $settings,

   874   );

   875 }

   876 

   877 /**

   878  * Creates a Drupal Ajax 'insert/replaceWith' command.

   879  *

   880  * The 'insert/replaceWith' command instructs the client to use jQuery's

   881  * replaceWith() method to replace each element matched matched by the given

   882  * selector with the given HTML.

   883  *

   884  * This command is implemented by Drupal.ajax.prototype.commands.insert()

   885  * defined in misc/ajax.js.

   886  *

   887  * @param $selector

   888  *   A jQuery selector string. If the command is a response to a request from

   889  *   an #ajax form element then this value can be NULL.

   890  * @param $html

   891  *   The data to use with the jQuery replaceWith() method.

   892  * @param $settings

   893  *   An optional array of settings that will be used for this command only.

   894  *

   895  * @return

   896  *   An array suitable for use with the ajax_render() function.

   897  *

   898  * See

   899  * @link http://docs.jquery.com/Manipulation/replaceWith#content jQuery replaceWith command @endlink

   900  */

   901 function ajax_command_replace($selector, $html, $settings = NULL) {

   902   return array(

   903     'command' => 'insert',

   904     'method' => 'replaceWith',

   905     'selector' => $selector,

   906     'data' => $html,

   907     'settings' => $settings,

   908   );

   909 }

   910 

   911 /**

   912  * Creates a Drupal Ajax 'insert/html' command.

   913  *

   914  * The 'insert/html' command instructs the client to use jQuery's html()

   915  * method to set the HTML content of each element matched by the given

   916  * selector while leaving the outer tags intact.

   917  *

   918  * This command is implemented by Drupal.ajax.prototype.commands.insert()

   919  * defined in misc/ajax.js.

   920  *

   921  * @param $selector

   922  *   A jQuery selector string. If the command is a response to a request from

   923  *   an #ajax form element then this value can be NULL.

   924  * @param $html

   925  *   The data to use with the jQuery html() method.

   926  * @param $settings

   927  *   An optional array of settings that will be used for this command only.

   928  *

   929  * @return

   930  *   An array suitable for use with the ajax_render() function.

   931  *

   932  * @see http://docs.jquery.com/Attributes/html#val

   933  */

   934 function ajax_command_html($selector, $html, $settings = NULL) {

   935   return array(

   936     'command' => 'insert',

   937     'method' => 'html',

   938     'selector' => $selector,

   939     'data' => $html,

   940     'settings' => $settings,

   941   );

   942 }

   943 

   944 /**

   945  * Creates a Drupal Ajax 'insert/prepend' command.

   946  *

   947  * The 'insert/prepend' command instructs the client to use jQuery's prepend()

   948  * method to prepend the given HTML content to the inside each element matched

   949  * by the given selector.

   950  *

   951  * This command is implemented by Drupal.ajax.prototype.commands.insert()

   952  * defined in misc/ajax.js.

   953  *

   954  * @param $selector

   955  *   A jQuery selector string. If the command is a response to a request from

   956  *   an #ajax form element then this value can be NULL.

   957  * @param $html

   958  *   The data to use with the jQuery prepend() method.

   959  * @param $settings

   960  *   An optional array of settings that will be used for this command only.

   961  *

   962  * @return

   963  *   An array suitable for use with the ajax_render() function.

   964  *

   965  * @see http://docs.jquery.com/Manipulation/prepend#content

   966  */

   967 function ajax_command_prepend($selector, $html, $settings = NULL) {

   968   return array(

   969     'command' => 'insert',

   970     'method' => 'prepend',

   971     'selector' => $selector,

   972     'data' => $html,

   973     'settings' => $settings,

   974   );

   975 }

   976 

   977 /**

   978  * Creates a Drupal Ajax 'insert/append' command.

   979  *

   980  * The 'insert/append' command instructs the client to use jQuery's append()

   981  * method to append the given HTML content to the inside of each element matched

   982  * by the given selector.

   983  *

   984  * This command is implemented by Drupal.ajax.prototype.commands.insert()

   985  * defined in misc/ajax.js.

   986  *

   987  * @param $selector

   988  *   A jQuery selector string. If the command is a response to a request from

   989  *   an #ajax form element then this value can be NULL.

   990  * @param $html

   991  *   The data to use with the jQuery append() method.

   992  * @param $settings

   993  *   An optional array of settings that will be used for this command only.

   994  *

   995  * @return

   996  *   An array suitable for use with the ajax_render() function.

   997  *

   998  * @see http://docs.jquery.com/Manipulation/append#content

   999  */

  1000 function ajax_command_append($selector, $html, $settings = NULL) {

  1001   return array(

  1002     'command' => 'insert',

  1003     'method' => 'append',

  1004     'selector' => $selector,

  1005     'data' => $html,

  1006     'settings' => $settings,

  1007   );

  1008 }

  1009 

  1010 /**

  1011  * Creates a Drupal Ajax 'insert/after' command.

  1012  *

  1013  * The 'insert/after' command instructs the client to use jQuery's after()

  1014  * method to insert the given HTML content after each element matched by

  1015  * the given selector.

  1016  *

  1017  * This command is implemented by Drupal.ajax.prototype.commands.insert()

  1018  * defined in misc/ajax.js.

  1019  *

  1020  * @param $selector

  1021  *   A jQuery selector string. If the command is a response to a request from

  1022  *   an #ajax form element then this value can be NULL.

  1023  * @param $html

  1024  *   The data to use with the jQuery after() method.

  1025  * @param $settings

  1026  *   An optional array of settings that will be used for this command only.

  1027  *

  1028  * @return

  1029  *   An array suitable for use with the ajax_render() function.

  1030  *

  1031  * @see http://docs.jquery.com/Manipulation/after#content

  1032  */

  1033 function ajax_command_after($selector, $html, $settings = NULL) {

  1034   return array(

  1035     'command' => 'insert',

  1036     'method' => 'after',

  1037     'selector' => $selector,

  1038     'data' => $html,

  1039     'settings' => $settings,

  1040   );

  1041 }

  1042 

  1043 /**

  1044  * Creates a Drupal Ajax 'insert/before' command.

  1045  *

  1046  * The 'insert/before' command instructs the client to use jQuery's before()

  1047  * method to insert the given HTML content before each of elements matched by

  1048  * the given selector.

  1049  *

  1050  * This command is implemented by Drupal.ajax.prototype.commands.insert()

  1051  * defined in misc/ajax.js.

  1052  *

  1053  * @param $selector

  1054  *   A jQuery selector string. If the command is a response to a request from

  1055  *   an #ajax form element then this value can be NULL.

  1056  * @param $html

  1057  *   The data to use with the jQuery before() method.

  1058  * @param $settings

  1059  *   An optional array of settings that will be used for this command only.

  1060  *

  1061  * @return

  1062  *   An array suitable for use with the ajax_render() function.

  1063  *

  1064  * @see http://docs.jquery.com/Manipulation/before#content

  1065  */

  1066 function ajax_command_before($selector, $html, $settings = NULL) {

  1067   return array(

  1068     'command' => 'insert',

  1069     'method' => 'before',

  1070     'selector' => $selector,

  1071     'data' => $html,

  1072     'settings' => $settings,

  1073   );

  1074 }

  1075 

  1076 /**

  1077  * Creates a Drupal Ajax 'remove' command.

  1078  *

  1079  * The 'remove' command instructs the client to use jQuery's remove() method

  1080  * to remove each of elements matched by the given selector, and everything

  1081  * within them.

  1082  *

  1083  * This command is implemented by Drupal.ajax.prototype.commands.remove()

  1084  * defined in misc/ajax.js.

  1085  *

  1086  * @param $selector

  1087  *   A jQuery selector string. If the command is a response to a request from

  1088  *   an #ajax form element then this value can be NULL.

  1089  *

  1090  * @return

  1091  *   An array suitable for use with the ajax_render() function.

  1092  *

  1093  * @see http://docs.jquery.com/Manipulation/remove#expr

  1094  */

  1095 function ajax_command_remove($selector) {

  1096   return array(

  1097     'command' => 'remove',

  1098     'selector' => $selector,

  1099   );

  1100 }

  1101 

  1102 /**

  1103  * Creates a Drupal Ajax 'changed' command.

  1104  *

  1105  * This command instructs the client to mark each of the elements matched by the

  1106  * given selector as 'ajax-changed'.

  1107  *

  1108  * This command is implemented by Drupal.ajax.prototype.commands.changed()

  1109  * defined in misc/ajax.js.

  1110  *

  1111  * @param $selector

  1112  *   A jQuery selector string. If the command is a response to a request from

  1113  *   an #ajax form element then this value can be NULL.

  1114  * @param $asterisk

  1115  *   An optional CSS selector which must be inside $selector. If specified,

  1116  *   an asterisk will be appended to the HTML inside the $asterisk selector.

  1117  *

  1118  * @return

  1119  *   An array suitable for use with the ajax_render() function.

  1120  */

  1121 function ajax_command_changed($selector, $asterisk = '') {

  1122   return array(

  1123     'command' => 'changed',

  1124     'selector' => $selector,

  1125     'asterisk' => $asterisk,

  1126   );

  1127 }

  1128 

  1129 /**

  1130  * Creates a Drupal Ajax 'css' command.

  1131  *

  1132  * The 'css' command will instruct the client to use the jQuery css() method

  1133  * to apply the CSS arguments to elements matched by the given selector.

  1134  *

  1135  * This command is implemented by Drupal.ajax.prototype.commands.css()

  1136  * defined in misc/ajax.js.