Project

General

Profile

Paste
Download (49.3 KB) Statistics
| Branch: | Revision:

root / drupal7 / includes / ajax.inc @ b0dc3a2e

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.
1137
 *
1138
 * @param $selector
1139
 *   A jQuery selector string. If the command is a response to a request from
1140
 *   an #ajax form element then this value can be NULL.
1141
 * @param $argument
1142
 *   An array of key/value pairs to set in the CSS for the selector.
1143
 *
1144
 * @return
1145
 *   An array suitable for use with the ajax_render() function.
1146
 *
1147
 * @see http://docs.jquery.com/CSS/css#properties
1148
 */
1149
function ajax_command_css($selector, $argument) {
1150
  return array(
1151
    'command' => 'css',
1152
    'selector' => $selector,
1153
    'argument' => $argument,
1154
  );
1155
}
1156

    
1157
/**
1158
 * Creates a Drupal Ajax 'settings' command.
1159
 *
1160
 * The 'settings' command instructs the client either to use the given array as
1161
 * the settings for ajax-loaded content or to extend Drupal.settings with the
1162
 * given array, depending on the value of the $merge parameter.
1163
 *
1164
 * This command is implemented by Drupal.ajax.prototype.commands.settings()
1165
 * defined in misc/ajax.js.
1166
 *
1167
 * @param $argument
1168
 *   An array of key/value pairs to add to the settings. This will be utilized
1169
 *   for all commands after this if they do not include their own settings
1170
 *   array.
1171
 * @param $merge
1172
 *   Whether or not the passed settings in $argument should be merged into the
1173
 *   global Drupal.settings on the page. By default (FALSE), the settings that
1174
 *   are passed to Drupal.attachBehaviors will not include the global
1175
 *   Drupal.settings.
1176
 *
1177
 * @return
1178
 *   An array suitable for use with the ajax_render() function.
1179
 */
1180
function ajax_command_settings($argument, $merge = FALSE) {
1181
  return array(
1182
    'command' => 'settings',
1183
    'settings' => $argument,
1184
    'merge' => $merge,
1185
  );
1186
}
1187

    
1188
/**
1189
 * Creates a Drupal Ajax 'data' command.
1190
 *
1191
 * The 'data' command instructs the client to attach the name=value pair of
1192
 * data to the selector via jQuery's data cache.
1193
 *
1194
 * This command is implemented by Drupal.ajax.prototype.commands.data()
1195
 * defined in misc/ajax.js.
1196
 *
1197
 * @param $selector
1198
 *   A jQuery selector string. If the command is a response to a request from
1199
 *   an #ajax form element then this value can be NULL.
1200
 * @param $name
1201
 *   The name or key (in the key value pair) of the data attached to this
1202
 *   selector.
1203
 * @param $value
1204
 *   The value of the data. Not just limited to strings can be any format.
1205
 *
1206
 * @return
1207
 *   An array suitable for use with the ajax_render() function.
1208
 *
1209
 * @see http://docs.jquery.com/Core/data#namevalue
1210
 */
1211
function ajax_command_data($selector, $name, $value) {
1212
  return array(
1213
    'command' => 'data',
1214
    'selector' => $selector,
1215
    'name' => $name,
1216
    'value' => $value,
1217
  );
1218
}
1219

    
1220
/**
1221
 * Creates a Drupal Ajax 'invoke' command.
1222
 *
1223
 * The 'invoke' command will instruct the client to invoke the given jQuery
1224
 * method with the supplied arguments on the elements matched by the given
1225
 * selector. Intended for simple jQuery commands, such as attr(), addClass(),
1226
 * removeClass(), toggleClass(), etc.
1227
 *
1228
 * This command is implemented by Drupal.ajax.prototype.commands.invoke()
1229
 * defined in misc/ajax.js.
1230
 *
1231
 * @param $selector
1232
 *   A jQuery selector string. If the command is a response to a request from
1233
 *   an #ajax form element then this value can be NULL.
1234
 * @param $method
1235
 *   The jQuery method to invoke.
1236
 * @param $arguments
1237
 *   (optional) A list of arguments to the jQuery $method, if any.
1238
 *
1239
 * @return
1240
 *   An array suitable for use with the ajax_render() function.
1241
 */
1242
function ajax_command_invoke($selector, $method, array $arguments = array()) {
1243
  return array(
1244
    'command' => 'invoke',
1245
    'selector' => $selector,
1246
    'method' => $method,
1247
    'arguments' => $arguments,
1248
  );
1249
}
1250

    
1251
/**
1252
 * Creates a Drupal Ajax 'restripe' command.
1253
 *
1254
 * The 'restripe' command instructs the client to restripe a table. This is
1255
 * usually used after a table has been modified by a replace or append command.
1256
 *
1257
 * This command is implemented by Drupal.ajax.prototype.commands.restripe()
1258
 * defined in misc/ajax.js.
1259
 *
1260
 * @param $selector
1261
 *   A jQuery selector string.
1262
 *
1263
 * @return
1264
 *   An array suitable for use with the ajax_render() function.
1265
 */
1266
function ajax_command_restripe($selector) {
1267
  return array(
1268
    'command' => 'restripe',
1269
    'selector' => $selector,
1270
  );
1271
}
1272

    
1273
/**
1274
 * Creates a Drupal Ajax 'update_build_id' command.
1275
 *
1276
 * This command updates the value of a hidden form_build_id input element on a
1277
 * form. It requires the form passed in to have keys for both the old build ID
1278
 * in #build_id_old and the new build ID in #build_id.
1279
 *
1280
 * The primary use case for this Ajax command is to serve a new build ID to a
1281
 * form served from the cache to an anonymous user, preventing one anonymous
1282
 * user from accessing the form state of another anonymous users on Ajax enabled
1283
 * forms.
1284
 *
1285
 * @param $form
1286
 *   The form array representing the form whose build ID should be updated.
1287
 */
1288
function ajax_command_update_build_id($form) {
1289
  return array(
1290
    'command' => 'updateBuildId',
1291
    'old' => $form['#build_id_old'],
1292
    'new' => $form['#build_id'],
1293
  );
1294
}
1295

    
1296
/**
1297
 * Creates a Drupal Ajax 'add_css' command.
1298
 *
1299
 * This method will add css via ajax in a cross-browser compatible way.
1300
 *
1301
 * This command is implemented by Drupal.ajax.prototype.commands.add_css()
1302
 * defined in misc/ajax.js.
1303
 *
1304
 * @param $styles
1305
 *   A string that contains the styles to be added.
1306
 *
1307
 * @return
1308
 *   An array suitable for use with the ajax_render() function.
1309
 *
1310
 * @see misc/ajax.js
1311
 */
1312
function ajax_command_add_css($styles) {
1313
  return array(
1314
    'command' => 'add_css',
1315
    'data' => $styles,
1316
  );
1317
}