ajax.inc 48 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259
  1. <?php
  2. /**
  3. * @file
  4. * Functions for use with Drupal's Ajax framework.
  5. */
  6. /**
  7. * @defgroup ajax Ajax framework
  8. * @{
  9. * Functions for Drupal's Ajax framework.
  10. *
  11. * Drupal's Ajax framework is used to dynamically update parts of a page's HTML
  12. * based on data from the server. Upon a specified event, such as a button
  13. * click, a callback function is triggered which performs server-side logic and
  14. * may return updated markup, which is then replaced on-the-fly with no page
  15. * refresh necessary.
  16. *
  17. * This framework creates a PHP macro language that allows the server to
  18. * instruct JavaScript to perform actions on the client browser. When using
  19. * forms, it can be used with the #ajax property.
  20. * The #ajax property can be used to bind events to the Ajax framework. By
  21. * default, #ajax uses 'system/ajax' as its path for submission and thus calls
  22. * ajax_form_callback() and a defined #ajax['callback'] function.
  23. * However, you may optionally specify a different path to request or a
  24. * different callback function to invoke, which can return updated HTML or can
  25. * also return a richer set of
  26. * @link ajax_commands Ajax framework commands @endlink.
  27. *
  28. * Standard form handling is as follows:
  29. * - A form element has a #ajax property that includes #ajax['callback'] and
  30. * omits #ajax['path']. See below about using #ajax['path'] to implement
  31. * advanced use-cases that require something other than standard form
  32. * handling.
  33. * - On the specified element, Ajax processing is triggered by a change to
  34. * that element.
  35. * - The browser submits an HTTP POST request to the 'system/ajax' Drupal
  36. * path.
  37. * - The menu page callback for 'system/ajax', ajax_form_callback(), calls
  38. * drupal_process_form() to process the form submission and rebuild the
  39. * form if necessary. The form is processed in much the same way as if it
  40. * were submitted without Ajax, with the same #process functions and
  41. * validation and submission handlers called in either case, making it easy
  42. * to create Ajax-enabled forms that degrade gracefully when JavaScript is
  43. * disabled.
  44. * - After form processing is complete, ajax_form_callback() calls the
  45. * function named by #ajax['callback'], which returns the form element that
  46. * has been updated and needs to be returned to the browser, or
  47. * alternatively, an array of custom Ajax commands.
  48. * - The page delivery callback for 'system/ajax', ajax_deliver(), renders the
  49. * element returned by #ajax['callback'], and returns the JSON string
  50. * created by ajax_render() to the browser.
  51. * - The browser unserializes the returned JSON string into an array of
  52. * command objects and executes each command, resulting in the old page
  53. * content within and including the HTML element specified by
  54. * #ajax['wrapper'] being replaced by the new content returned by
  55. * #ajax['callback'], using a JavaScript animation effect specified by
  56. * #ajax['effect'].
  57. *
  58. * A simple example of basic Ajax use from the
  59. * @link http://drupal.org/project/examples Examples module @endlink follows:
  60. * @code
  61. * function main_page() {
  62. * return drupal_get_form('ajax_example_simplest');
  63. * }
  64. *
  65. * function ajax_example_simplest($form, &$form_state) {
  66. * $form = array();
  67. * $form['changethis'] = array(
  68. * '#type' => 'select',
  69. * '#options' => array(
  70. * 'one' => 'one',
  71. * 'two' => 'two',
  72. * 'three' => 'three',
  73. * ),
  74. * '#ajax' => array(
  75. * 'callback' => 'ajax_example_simplest_callback',
  76. * 'wrapper' => 'replace_textfield_div',
  77. * ),
  78. * );
  79. * // This entire form element will be replaced with an updated value.
  80. * $form['replace_textfield'] = array(
  81. * '#type' => 'textfield',
  82. * '#title' => t("The default value will be changed"),
  83. * '#description' => t("Say something about why you chose") . "'" .
  84. * (!empty($form_state['values']['changethis'])
  85. * ? $form_state['values']['changethis'] : t("Not changed yet")) . "'",
  86. * '#prefix' => '<div id="replace_textfield_div">',
  87. * '#suffix' => '</div>',
  88. * );
  89. * return $form;
  90. * }
  91. *
  92. * function ajax_example_simplest_callback($form, $form_state) {
  93. * // The form has already been submitted and updated. We can return the replaced
  94. * // item as it is.
  95. * return $form['replace_textfield'];
  96. * }
  97. * @endcode
  98. *
  99. * In the above example, the 'changethis' element is Ajax-enabled. The default
  100. * #ajax['event'] is 'change', so when the 'changethis' element changes,
  101. * an Ajax call is made. The form is submitted and reprocessed, and then the
  102. * callback is called. In this case, the form has been automatically
  103. * built changing $form['replace_textfield']['#description'], so the callback
  104. * just returns that part of the form.
  105. *
  106. * To implement Ajax handling in a form, add '#ajax' to the form
  107. * definition of a field. That field will trigger an Ajax event when it is
  108. * clicked (or changed, depending on the kind of field). #ajax supports
  109. * the following parameters (either 'path' or 'callback' is required at least):
  110. * - #ajax['callback']: The callback to invoke to handle the server side of the
  111. * Ajax event, which will receive a $form and $form_state as arguments, and
  112. * returns a renderable array (most often a form or form fragment), an HTML
  113. * string, or an array of Ajax commands. If returning a renderable array or
  114. * a string, the value will replace the original element named in
  115. * #ajax['wrapper'], and
  116. * theme_status_messages()
  117. * will be prepended to that
  118. * element. (If the status messages are not wanted, return an array
  119. * of Ajax commands instead.)
  120. * #ajax['wrapper']. If an array of Ajax commands is returned, it will be
  121. * executed by the calling code.
  122. * - #ajax['path']: The menu path to use for the request. This is often omitted
  123. * and the default is used. This path should map
  124. * to a menu page callback that returns data using ajax_render(). Defaults to
  125. * 'system/ajax', which invokes ajax_form_callback(), eventually calling
  126. * the function named in #ajax['callback']. If you use a custom
  127. * path, you must set up the menu entry and handle the entire callback in your
  128. * own code.
  129. * - #ajax['wrapper']: The CSS ID of the area to be replaced by the content
  130. * returned by the #ajax['callback'] function. The content returned from
  131. * the callback will replace the entire element named by #ajax['wrapper'].
  132. * The wrapper is usually created using #prefix and #suffix properties in the
  133. * form. Note that this is the wrapper ID, not a CSS selector. So to replace
  134. * the element referred to by the CSS selector #some-selector on the page,
  135. * use #ajax['wrapper'] = 'some-selector', not '#some-selector'.
  136. * - #ajax['effect']: The jQuery effect to use when placing the new HTML.
  137. * Defaults to no effect. Valid options are 'none', 'slide', or 'fade'.
  138. * - #ajax['speed']: The effect speed to use. Defaults to 'slow'. May be
  139. * 'slow', 'fast' or a number in milliseconds which represents the length
  140. * of time the effect should run.
  141. * - #ajax['event']: The JavaScript event to respond to. This is normally
  142. * selected automatically for the type of form widget being used, and
  143. * is only needed if you need to override the default behavior.
  144. * - #ajax['prevent']: A JavaScript event to prevent when 'event' is triggered.
  145. * Defaults to 'click' for #ajax on #type 'submit', 'button', and
  146. * 'image_button'. Multiple events may be specified separated by spaces.
  147. * For example, when binding #ajax behaviors to form buttons, pressing the
  148. * ENTER key within a textfield triggers the 'click' event of the form's first
  149. * submit button. Triggering Ajax in this situation leads to problems, like
  150. * breaking autocomplete textfields. Because of that, Ajax behaviors are bound
  151. * to the 'mousedown' event on form buttons by default. However, binding to
  152. * 'mousedown' rather than 'click' means that it is possible to trigger a
  153. * click by pressing the mouse, holding the mouse button down until the Ajax
  154. * request is complete and the button is re-enabled, and then releasing the
  155. * mouse button. For this case, 'prevent' can be set to 'click', so an
  156. * additional event handler is bound to prevent such a click from triggering a
  157. * non-Ajax form submission. This also prevents a textfield's ENTER press
  158. * triggering a button's non-Ajax form submission behavior.
  159. * - #ajax['method']: The jQuery method to use to place the new HTML.
  160. * Defaults to 'replaceWith'. May be: 'replaceWith', 'append', 'prepend',
  161. * 'before', 'after', or 'html'. See the
  162. * @link http://api.jquery.com/category/manipulation/ jQuery manipulators documentation @endlink
  163. * for more information on these methods.
  164. * - #ajax['progress']: Choose either a throbber or progress bar that is
  165. * displayed while awaiting a response from the callback, and add an optional
  166. * message. Possible keys: 'type', 'message', 'url', 'interval'.
  167. * More information is available in the
  168. * @link forms_api_reference.html Form API Reference @endlink
  169. *
  170. * In addition to using Form API for doing in-form modification, Ajax may be
  171. * enabled by adding classes to buttons and links. By adding the 'use-ajax'
  172. * class to a link, the link will be loaded via an Ajax call. When using this
  173. * method, the href of the link can contain '/nojs/' as part of the path. When
  174. * the Ajax framework makes the request, it will convert this to '/ajax/'.
  175. * The server is then able to easily tell if this request was made through an
  176. * actual Ajax request or in a degraded state, and respond appropriately.
  177. *
  178. * Similarly, submit buttons can be given the class 'use-ajax-submit'. The
  179. * form will then be submitted via Ajax to the path specified in the #action.
  180. * Like the ajax-submit class above, this path will have '/nojs/' replaced with
  181. * '/ajax/' so that the submit handler can tell if the form was submitted
  182. * in a degraded state or not.
  183. *
  184. * When responding to Ajax requests, the server should do what it needs to do
  185. * for that request, then create a commands array. This commands array will
  186. * be converted to a JSON object and returned to the client, which will then
  187. * iterate over the array and process it like a macro language.
  188. *
  189. * Each command item is an associative array which will be converted to a
  190. * command object on the JavaScript side. $command_item['command'] is the type
  191. * of command, e.g. 'alert' or 'replace', and will correspond to a method in the
  192. * Drupal.ajax[command] space. The command array may contain any other data that
  193. * the command needs to process, e.g. 'method', 'selector', 'settings', etc.
  194. *
  195. * Commands are usually created with a couple of helper functions, so they
  196. * look like this:
  197. * @code
  198. * $commands = array();
  199. * // Replace the content of '#object-1' on the page with 'some html here'.
  200. * $commands[] = ajax_command_replace('#object-1', 'some html here');
  201. * // Add a visual "changed" marker to the '#object-1' element.
  202. * $commands[] = ajax_command_changed('#object-1');
  203. * // Menu 'page callback' and #ajax['callback'] functions are supposed to
  204. * // return render arrays. If returning an Ajax commands array, it must be
  205. * // encapsulated in a render array structure.
  206. * return array('#type' => 'ajax', '#commands' => $commands);
  207. * @endcode
  208. *
  209. * When returning an Ajax command array, it is often useful to have
  210. * status messages rendered along with other tasks in the command array.
  211. * In that case the the Ajax commands array may be constructed like this:
  212. * @code
  213. * $commands = array();
  214. * $commands[] = ajax_command_replace(NULL, $output);
  215. * $commands[] = ajax_command_prepend(NULL, theme('status_messages'));
  216. * return array('#type' => 'ajax', '#commands' => $commands);
  217. * @endcode
  218. *
  219. * See @link ajax_commands Ajax framework commands @endlink
  220. */
  221. /**
  222. * Renders a commands array into JSON.
  223. *
  224. * @param $commands
  225. * A list of macro commands generated by the use of ajax_command_*()
  226. * functions.
  227. */
  228. function ajax_render($commands = array()) {
  229. // Ajax responses aren't rendered with html.tpl.php, so we have to call
  230. // drupal_get_css() and drupal_get_js() here, in order to have new files added
  231. // during this request to be loaded by the page. We only want to send back
  232. // files that the page hasn't already loaded, so we implement simple diffing
  233. // logic using array_diff_key().
  234. foreach (array('css', 'js') as $type) {
  235. // It is highly suspicious if $_POST['ajax_page_state'][$type] is empty,
  236. // since the base page ought to have at least one JS file and one CSS file
  237. // loaded. It probably indicates an error, and rather than making the page
  238. // reload all of the files, instead we return no new files.
  239. if (empty($_POST['ajax_page_state'][$type])) {
  240. $items[$type] = array();
  241. }
  242. else {
  243. $function = 'drupal_add_' . $type;
  244. $items[$type] = $function();
  245. drupal_alter($type, $items[$type]);
  246. // @todo Inline CSS and JS items are indexed numerically. These can't be
  247. // reliably diffed with array_diff_key(), since the number can change
  248. // due to factors unrelated to the inline content, so for now, we strip
  249. // the inline items from Ajax responses, and can add support for them
  250. // when drupal_add_css() and drupal_add_js() are changed to use a hash
  251. // of the inline content as the array key.
  252. foreach ($items[$type] as $key => $item) {
  253. if (is_numeric($key)) {
  254. unset($items[$type][$key]);
  255. }
  256. }
  257. // Ensure that the page doesn't reload what it already has.
  258. $items[$type] = array_diff_key($items[$type], $_POST['ajax_page_state'][$type]);
  259. }
  260. }
  261. // Render the HTML to load these files, and add AJAX commands to insert this
  262. // HTML in the page. We pass TRUE as the $skip_alter argument to prevent the
  263. // data from being altered again, as we already altered it above. Settings are
  264. // handled separately, afterwards.
  265. if (isset($items['js']['settings'])) {
  266. unset($items['js']['settings']);
  267. }
  268. $styles = drupal_get_css($items['css'], TRUE);
  269. $scripts_footer = drupal_get_js('footer', $items['js'], TRUE);
  270. $scripts_header = drupal_get_js('header', $items['js'], TRUE);
  271. $extra_commands = array();
  272. if (!empty($styles)) {
  273. $extra_commands[] = ajax_command_prepend('head', $styles);
  274. }
  275. if (!empty($scripts_header)) {
  276. $extra_commands[] = ajax_command_prepend('head', $scripts_header);
  277. }
  278. if (!empty($scripts_footer)) {
  279. $extra_commands[] = ajax_command_append('body', $scripts_footer);
  280. }
  281. if (!empty($extra_commands)) {
  282. $commands = array_merge($extra_commands, $commands);
  283. }
  284. // Now add a command to merge changes and additions to Drupal.settings.
  285. $scripts = drupal_add_js();
  286. if (!empty($scripts['settings'])) {
  287. $settings = $scripts['settings'];
  288. array_unshift($commands, ajax_command_settings(call_user_func_array('array_merge_recursive', $settings['data']), TRUE));
  289. }
  290. // Allow modules to alter any Ajax response.
  291. drupal_alter('ajax_render', $commands);
  292. return drupal_json_encode($commands);
  293. }
  294. /**
  295. * Gets a form submitted via #ajax during an Ajax callback.
  296. *
  297. * This will load a form from the form cache used during Ajax operations. It
  298. * pulls the form info from $_POST.
  299. *
  300. * @return
  301. * An array containing the $form, $form_state, $form_id, $form_build_id and an
  302. * initial list of Ajax $commands. Use the list() function to break these
  303. * apart:
  304. * @code
  305. * list($form, $form_state, $form_id, $form_build_id, $commands) = ajax_get_form();
  306. * @endcode
  307. */
  308. function ajax_get_form() {
  309. $form_state = form_state_defaults();
  310. $form_build_id = $_POST['form_build_id'];
  311. // Get the form from the cache.
  312. $form = form_get_cache($form_build_id, $form_state);
  313. if (!$form) {
  314. // If $form cannot be loaded from the cache, the form_build_id in $_POST
  315. // must be invalid, which means that someone performed a POST request onto
  316. // system/ajax without actually viewing the concerned form in the browser.
  317. // This is likely a hacking attempt as it never happens under normal
  318. // circumstances, so we just do nothing.
  319. watchdog('ajax', 'Invalid form POST data.', array(), WATCHDOG_WARNING);
  320. drupal_exit();
  321. }
  322. // When a page level cache is enabled, the form-build id might have been
  323. // replaced from within form_get_cache. If this is the case, it is also
  324. // necessary to update it in the browser by issuing an appropriate Ajax
  325. // command.
  326. $commands = array();
  327. if (isset($form['#build_id_old']) && $form['#build_id_old'] != $form['#build_id']) {
  328. // If the form build ID has changed, issue an Ajax command to update it.
  329. $commands[] = ajax_command_update_build_id($form);
  330. $form_build_id = $form['#build_id'];
  331. }
  332. // Since some of the submit handlers are run, redirects need to be disabled.
  333. $form_state['no_redirect'] = TRUE;
  334. // When a form is rebuilt after Ajax processing, its #build_id and #action
  335. // should not change.
  336. // @see drupal_rebuild_form()
  337. $form_state['rebuild_info']['copy']['#build_id'] = TRUE;
  338. $form_state['rebuild_info']['copy']['#action'] = TRUE;
  339. // The form needs to be processed; prepare for that by setting a few internal
  340. // variables.
  341. $form_state['input'] = $_POST;
  342. $form_id = $form['#form_id'];
  343. return array($form, $form_state, $form_id, $form_build_id, $commands);
  344. }
  345. /**
  346. * Menu callback; handles Ajax requests for the #ajax Form API property.
  347. *
  348. * This rebuilds the form from cache and invokes the defined #ajax['callback']
  349. * to return an Ajax command structure for JavaScript. In case no 'callback' has
  350. * been defined, nothing will happen.
  351. *
  352. * The Form API #ajax property can be set both for buttons and other input
  353. * elements.
  354. *
  355. * This function is also the canonical example of how to implement
  356. * #ajax['path']. If processing is required that cannot be accomplished with
  357. * a callback, re-implement this function and set #ajax['path'] to the
  358. * enhanced function.
  359. *
  360. * @see system_menu()
  361. */
  362. function ajax_form_callback() {
  363. list($form, $form_state, $form_id, $form_build_id, $commands) = ajax_get_form();
  364. drupal_process_form($form['#form_id'], $form, $form_state);
  365. // We need to return the part of the form (or some other content) that needs
  366. // to be re-rendered so the browser can update the page with changed content.
  367. // Since this is the generic menu callback used by many Ajax elements, it is
  368. // up to the #ajax['callback'] function of the element (may or may not be a
  369. // button) that triggered the Ajax request to determine what needs to be
  370. // rendered.
  371. if (!empty($form_state['triggering_element'])) {
  372. $callback = $form_state['triggering_element']['#ajax']['callback'];
  373. }
  374. if (!empty($callback) && function_exists($callback)) {
  375. $result = $callback($form, $form_state);
  376. if (!(is_array($result) && isset($result['#type']) && $result['#type'] == 'ajax')) {
  377. // Turn the response into a #type=ajax array if it isn't one already.
  378. $result = array(
  379. '#type' => 'ajax',
  380. '#commands' => ajax_prepare_response($result),
  381. );
  382. }
  383. $result['#commands'] = array_merge($commands, $result['#commands']);
  384. return $result;
  385. }
  386. }
  387. /**
  388. * Theme callback for Ajax requests.
  389. *
  390. * Many different pages can invoke an Ajax request to system/ajax or another
  391. * generic Ajax path. It is almost always desired for an Ajax response to be
  392. * rendered using the same theme as the base page, because most themes are built
  393. * with the assumption that they control the entire page, so if the CSS for two
  394. * themes are both loaded for a given page, they may conflict with each other.
  395. * For example, Bartik is Drupal's default theme, and Seven is Drupal's default
  396. * administration theme. Depending on whether the "Use the administration theme
  397. * when editing or creating content" checkbox is checked, the node edit form may
  398. * be displayed in either theme, but the Ajax response to the Field module's
  399. * "Add another item" button should be rendered using the same theme as the rest
  400. * of the page. Therefore, system_menu() sets the 'theme callback' for
  401. * 'system/ajax' to this function, and it is recommended that modules
  402. * implementing other generic Ajax paths do the same.
  403. *
  404. * @see system_menu()
  405. * @see file_menu()
  406. */
  407. function ajax_base_page_theme() {
  408. if (!empty($_POST['ajax_page_state']['theme']) && !empty($_POST['ajax_page_state']['theme_token'])) {
  409. $theme = $_POST['ajax_page_state']['theme'];
  410. $token = $_POST['ajax_page_state']['theme_token'];
  411. // Prevent a request forgery from giving a person access to a theme they
  412. // shouldn't be otherwise allowed to see. However, since everyone is allowed
  413. // to see the default theme, token validation isn't required for that, and
  414. // bypassing it allows most use-cases to work even when accessed from the
  415. // page cache.
  416. if ($theme === variable_get('theme_default', 'bartik') || drupal_valid_token($token, $theme)) {
  417. return $theme;
  418. }
  419. }
  420. }
  421. /**
  422. * Packages and sends the result of a page callback as an Ajax response.
  423. *
  424. * This function is the equivalent of drupal_deliver_html_page(), but for Ajax
  425. * requests. Like that function, it:
  426. * - Adds needed HTTP headers.
  427. * - Prints rendered output.
  428. * - Performs end-of-request tasks.
  429. *
  430. * @param $page_callback_result
  431. * The result of a page callback. Can be one of:
  432. * - NULL: to indicate no content.
  433. * - An integer menu status constant: to indicate an error condition.
  434. * - A string of HTML content.
  435. * - A renderable array of content.
  436. *
  437. * @see drupal_deliver_html_page()
  438. */
  439. function ajax_deliver($page_callback_result) {
  440. // Browsers do not allow JavaScript to read the contents of a user's local
  441. // files. To work around that, the jQuery Form plugin submits forms containing
  442. // a file input element to an IFRAME, instead of using XHR. Browsers do not
  443. // normally expect JSON strings as content within an IFRAME, so the response
  444. // must be customized accordingly.
  445. // @see http://malsup.com/jquery/form/#file-upload
  446. // @see Drupal.ajax.prototype.beforeSend()
  447. $iframe_upload = !empty($_POST['ajax_iframe_upload']);
  448. // Emit a Content-Type HTTP header if none has been added by the page callback
  449. // or by a wrapping delivery callback.
  450. if (is_null(drupal_get_http_header('Content-Type'))) {
  451. if (!$iframe_upload) {
  452. // Standard JSON can be returned to a browser's XHR object, and to
  453. // non-browser user agents.
  454. // @see http://www.ietf.org/rfc/rfc4627.txt?number=4627
  455. drupal_add_http_header('Content-Type', 'application/json; charset=utf-8');
  456. }
  457. else {
  458. // Browser IFRAMEs expect HTML. With most other content types, Internet
  459. // Explorer presents the user with a download prompt.
  460. drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');
  461. }
  462. }
  463. // Print the response.
  464. $commands = ajax_prepare_response($page_callback_result);
  465. $json = ajax_render($commands);
  466. if (!$iframe_upload) {
  467. // Standard JSON can be returned to a browser's XHR object, and to
  468. // non-browser user agents.
  469. print $json;
  470. }
  471. else {
  472. // Browser IFRAMEs expect HTML. Browser extensions, such as Linkification
  473. // and Skype's Browser Highlighter, convert URLs, phone numbers, etc. into
  474. // links. This corrupts the JSON response. Protect the integrity of the
  475. // JSON data by making it the value of a textarea.
  476. // @see http://malsup.com/jquery/form/#file-upload
  477. // @see http://drupal.org/node/1009382
  478. print '<textarea>' . $json . '</textarea>';
  479. }
  480. // Perform end-of-request tasks.
  481. ajax_footer();
  482. }
  483. /**
  484. * Converts the return value of a page callback into an Ajax commands array.
  485. *
  486. * @param $page_callback_result
  487. * The result of a page callback. Can be one of:
  488. * - NULL: to indicate no content.
  489. * - An integer menu status constant: to indicate an error condition.
  490. * - A string of HTML content.
  491. * - A renderable array of content.
  492. *
  493. * @return
  494. * An Ajax commands array that can be passed to ajax_render().
  495. */
  496. function ajax_prepare_response($page_callback_result) {
  497. $commands = array();
  498. if (!isset($page_callback_result)) {
  499. // Simply delivering an empty commands array is sufficient. This results
  500. // in the Ajax request being completed, but nothing being done to the page.
  501. }
  502. elseif (is_int($page_callback_result)) {
  503. switch ($page_callback_result) {
  504. case MENU_NOT_FOUND:
  505. $commands[] = ajax_command_alert(t('The requested page could not be found.'));
  506. break;
  507. case MENU_ACCESS_DENIED:
  508. $commands[] = ajax_command_alert(t('You are not authorized to access this page.'));
  509. break;
  510. case MENU_SITE_OFFLINE:
  511. $commands[] = ajax_command_alert(filter_xss_admin(variable_get('maintenance_mode_message',
  512. t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal'))))));
  513. break;
  514. }
  515. }
  516. elseif (is_array($page_callback_result) && isset($page_callback_result['#type']) && ($page_callback_result['#type'] == 'ajax')) {
  517. // Complex Ajax callbacks can return a result that contains an error message
  518. // or a specific set of commands to send to the browser.
  519. $page_callback_result += element_info('ajax');
  520. $error = $page_callback_result['#error'];
  521. if (isset($error) && $error !== FALSE) {
  522. if ((empty($error) || $error === TRUE)) {
  523. $error = t('An error occurred while handling the request: The server received invalid input.');
  524. }
  525. $commands[] = ajax_command_alert($error);
  526. }
  527. else {
  528. $commands = $page_callback_result['#commands'];
  529. }
  530. }
  531. else {
  532. // Like normal page callbacks, simple Ajax callbacks can return HTML
  533. // content, as a string or render array. This HTML is inserted in some
  534. // relationship to #ajax['wrapper'], as determined by which jQuery DOM
  535. // manipulation method is used. The method used is specified by
  536. // #ajax['method']. The default method is 'replaceWith', which completely
  537. // replaces the old wrapper element and its content with the new HTML.
  538. $html = is_string($page_callback_result) ? $page_callback_result : drupal_render($page_callback_result);
  539. $commands[] = ajax_command_insert(NULL, $html);
  540. // Add the status messages inside the new content's wrapper element, so that
  541. // on subsequent Ajax requests, it is treated as old content.
  542. $commands[] = ajax_command_prepend(NULL, theme('status_messages'));
  543. }
  544. return $commands;
  545. }
  546. /**
  547. * Performs end-of-Ajax-request tasks.
  548. *
  549. * This function is the equivalent of drupal_page_footer(), but for Ajax
  550. * requests.
  551. *
  552. * @see drupal_page_footer()
  553. */
  554. function ajax_footer() {
  555. // Even for Ajax requests, invoke hook_exit() implementations. There may be
  556. // modules that need very fast Ajax responses, and therefore, run Ajax
  557. // requests with an early bootstrap.
  558. if (drupal_get_bootstrap_phase() == DRUPAL_BOOTSTRAP_FULL && (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update')) {
  559. module_invoke_all('exit');
  560. }
  561. // Commit the user session. See above comment about the possibility of this
  562. // function running without session.inc loaded.
  563. if (function_exists('drupal_session_commit')) {
  564. drupal_session_commit();
  565. }
  566. }
  567. /**
  568. * Form element processing handler for the #ajax form property.
  569. *
  570. * @param $element
  571. * An associative array containing the properties of the element.
  572. *
  573. * @return
  574. * The processed element.
  575. *
  576. * @see ajax_pre_render_element()
  577. */
  578. function ajax_process_form($element, &$form_state) {
  579. $element = ajax_pre_render_element($element);
  580. if (!empty($element['#ajax_processed'])) {
  581. $form_state['cache'] = TRUE;
  582. }
  583. return $element;
  584. }
  585. /**
  586. * Adds Ajax information about an element to communicate with JavaScript.
  587. *
  588. * If #ajax['path'] is set on an element, this additional JavaScript is added
  589. * to the page header to attach the Ajax behaviors. See ajax.js for more
  590. * information.
  591. *
  592. * @param $element
  593. * An associative array containing the properties of the element.
  594. * Properties used:
  595. * - #ajax['event']
  596. * - #ajax['prevent']
  597. * - #ajax['path']
  598. * - #ajax['options']
  599. * - #ajax['wrapper']
  600. * - #ajax['parameters']
  601. * - #ajax['effect']
  602. *
  603. * @return
  604. * The processed element with the necessary JavaScript attached to it.
  605. */
  606. function ajax_pre_render_element($element) {
  607. // Skip already processed elements.
  608. if (isset($element['#ajax_processed'])) {
  609. return $element;
  610. }
  611. // Initialize #ajax_processed, so we do not process this element again.
  612. $element['#ajax_processed'] = FALSE;
  613. // Nothing to do if there is neither a callback nor a path.
  614. if (!(isset($element['#ajax']['callback']) || isset($element['#ajax']['path']))) {
  615. return $element;
  616. }
  617. // Add a reasonable default event handler if none was specified.
  618. if (isset($element['#ajax']) && !isset($element['#ajax']['event'])) {
  619. switch ($element['#type']) {
  620. case 'submit':
  621. case 'button':
  622. case 'image_button':
  623. // Pressing the ENTER key within a textfield triggers the click event of
  624. // the form's first submit button. Triggering Ajax in this situation
  625. // leads to problems, like breaking autocomplete textfields, so we bind
  626. // to mousedown instead of click.
  627. // @see http://drupal.org/node/216059
  628. $element['#ajax']['event'] = 'mousedown';
  629. // Retain keyboard accessibility by setting 'keypress'. This causes
  630. // ajax.js to trigger 'event' when SPACE or ENTER are pressed while the
  631. // button has focus.
  632. $element['#ajax']['keypress'] = TRUE;
  633. // Binding to mousedown rather than click means that it is possible to
  634. // trigger a click by pressing the mouse, holding the mouse button down
  635. // until the Ajax request is complete and the button is re-enabled, and
  636. // then releasing the mouse button. Set 'prevent' so that ajax.js binds
  637. // an additional handler to prevent such a click from triggering a
  638. // non-Ajax form submission. This also prevents a textfield's ENTER
  639. // press triggering this button's non-Ajax form submission behavior.
  640. if (!isset($element['#ajax']['prevent'])) {
  641. $element['#ajax']['prevent'] = 'click';
  642. }
  643. break;
  644. case 'password':
  645. case 'textfield':
  646. case 'textarea':
  647. $element['#ajax']['event'] = 'blur';
  648. break;
  649. case 'radio':
  650. case 'checkbox':
  651. case 'select':
  652. $element['#ajax']['event'] = 'change';
  653. break;
  654. case 'link':
  655. $element['#ajax']['event'] = 'click';
  656. break;
  657. default:
  658. return $element;
  659. }
  660. }
  661. // Attach JavaScript settings to the element.
  662. if (isset($element['#ajax']['event'])) {
  663. $element['#attached']['library'][] = array('system', 'jquery.form');
  664. $element['#attached']['library'][] = array('system', 'drupal.ajax');
  665. $settings = $element['#ajax'];
  666. // Assign default settings.
  667. $settings += array(
  668. 'path' => 'system/ajax',
  669. 'options' => array(),
  670. );
  671. // @todo Legacy support. Remove in Drupal 8.
  672. if (isset($settings['method']) && $settings['method'] == 'replace') {
  673. $settings['method'] = 'replaceWith';
  674. }
  675. // Change path to URL.
  676. $settings['url'] = url($settings['path'], $settings['options']);
  677. unset($settings['path'], $settings['options']);
  678. // Add special data to $settings['submit'] so that when this element
  679. // triggers an Ajax submission, Drupal's form processing can determine which
  680. // element triggered it.
  681. // @see _form_element_triggered_scripted_submission()
  682. if (isset($settings['trigger_as'])) {
  683. // An element can add a 'trigger_as' key within #ajax to make the element
  684. // submit as though another one (for example, a non-button can use this
  685. // to submit the form as though a button were clicked). When using this,
  686. // the 'name' key is always required to identify the element to trigger
  687. // as. The 'value' key is optional, and only needed when multiple elements
  688. // share the same name, which is commonly the case for buttons.
  689. $settings['submit']['_triggering_element_name'] = $settings['trigger_as']['name'];
  690. if (isset($settings['trigger_as']['value'])) {
  691. $settings['submit']['_triggering_element_value'] = $settings['trigger_as']['value'];
  692. }
  693. unset($settings['trigger_as']);
  694. }
  695. elseif (isset($element['#name'])) {
  696. // Most of the time, elements can submit as themselves, in which case the
  697. // 'trigger_as' key isn't needed, and the element's name is used.
  698. $settings['submit']['_triggering_element_name'] = $element['#name'];
  699. // If the element is a (non-image) button, its name may not identify it
  700. // uniquely, in which case a match on value is also needed.
  701. // @see _form_button_was_clicked()
  702. if (isset($element['#button_type']) && empty($element['#has_garbage_value'])) {
  703. $settings['submit']['_triggering_element_value'] = $element['#value'];
  704. }
  705. }
  706. // Convert a simple #ajax['progress'] string into an array.
  707. if (isset($settings['progress']) && is_string($settings['progress'])) {
  708. $settings['progress'] = array('type' => $settings['progress']);
  709. }
  710. // Change progress path to a full URL.
  711. if (isset($settings['progress']['path'])) {
  712. $settings['progress']['url'] = url($settings['progress']['path']);
  713. unset($settings['progress']['path']);
  714. }
  715. $element['#attached']['js'][] = array(
  716. 'type' => 'setting',
  717. 'data' => array('ajax' => array($element['#id'] => $settings)),
  718. );
  719. // Indicate that Ajax processing was successful.
  720. $element['#ajax_processed'] = TRUE;
  721. }
  722. return $element;
  723. }
  724. /**
  725. * @} End of "defgroup ajax".
  726. */
  727. /**
  728. * @defgroup ajax_commands Ajax framework commands
  729. * @{
  730. * Functions to create various Ajax commands.
  731. *
  732. * These functions can be used to create arrays for use with the
  733. * ajax_render() function.
  734. */
  735. /**
  736. * Creates a Drupal Ajax 'alert' command.
  737. *
  738. * The 'alert' command instructs the client to display a JavaScript alert
  739. * dialog box.
  740. *
  741. * This command is implemented by Drupal.ajax.prototype.commands.alert()
  742. * defined in misc/ajax.js.
  743. *
  744. * @param $text
  745. * The message string to display to the user.
  746. *
  747. * @return
  748. * An array suitable for use with the ajax_render() function.
  749. */
  750. function ajax_command_alert($text) {
  751. return array(
  752. 'command' => 'alert',
  753. 'text' => $text,
  754. );
  755. }
  756. /**
  757. * Creates a Drupal Ajax 'insert' command using the method in #ajax['method'].
  758. *
  759. * This command instructs the client to insert the given HTML using whichever
  760. * jQuery DOM manipulation method has been specified in the #ajax['method']
  761. * variable of the element that triggered the request.
  762. *
  763. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  764. * defined in misc/ajax.js.
  765. *
  766. * @param $selector
  767. * A jQuery selector string. If the command is a response to a request from
  768. * an #ajax form element then this value can be NULL.
  769. * @param $html
  770. * The data to use with the jQuery method.
  771. * @param $settings
  772. * An optional array of settings that will be used for this command only.
  773. *
  774. * @return
  775. * An array suitable for use with the ajax_render() function.
  776. */
  777. function ajax_command_insert($selector, $html, $settings = NULL) {
  778. return array(
  779. 'command' => 'insert',
  780. 'method' => NULL,
  781. 'selector' => $selector,
  782. 'data' => $html,
  783. 'settings' => $settings,
  784. );
  785. }
  786. /**
  787. * Creates a Drupal Ajax 'insert/replaceWith' command.
  788. *
  789. * The 'insert/replaceWith' command instructs the client to use jQuery's
  790. * replaceWith() method to replace each element matched matched by the given
  791. * selector with the given HTML.
  792. *
  793. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  794. * defined in misc/ajax.js.
  795. *
  796. * @param $selector
  797. * A jQuery selector string. If the command is a response to a request from
  798. * an #ajax form element then this value can be NULL.
  799. * @param $html
  800. * The data to use with the jQuery replaceWith() method.
  801. * @param $settings
  802. * An optional array of settings that will be used for this command only.
  803. *
  804. * @return
  805. * An array suitable for use with the ajax_render() function.
  806. *
  807. * See
  808. * @link http://docs.jquery.com/Manipulation/replaceWith#content jQuery replaceWith command @endlink
  809. */
  810. function ajax_command_replace($selector, $html, $settings = NULL) {
  811. return array(
  812. 'command' => 'insert',
  813. 'method' => 'replaceWith',
  814. 'selector' => $selector,
  815. 'data' => $html,
  816. 'settings' => $settings,
  817. );
  818. }
  819. /**
  820. * Creates a Drupal Ajax 'insert/html' command.
  821. *
  822. * The 'insert/html' command instructs the client to use jQuery's html()
  823. * method to set the HTML content of each element matched by the given
  824. * selector while leaving the outer tags intact.
  825. *
  826. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  827. * defined in misc/ajax.js.
  828. *
  829. * @param $selector
  830. * A jQuery selector string. If the command is a response to a request from
  831. * an #ajax form element then this value can be NULL.
  832. * @param $html
  833. * The data to use with the jQuery html() method.
  834. * @param $settings
  835. * An optional array of settings that will be used for this command only.
  836. *
  837. * @return
  838. * An array suitable for use with the ajax_render() function.
  839. *
  840. * @see http://docs.jquery.com/Attributes/html#val
  841. */
  842. function ajax_command_html($selector, $html, $settings = NULL) {
  843. return array(
  844. 'command' => 'insert',
  845. 'method' => 'html',
  846. 'selector' => $selector,
  847. 'data' => $html,
  848. 'settings' => $settings,
  849. );
  850. }
  851. /**
  852. * Creates a Drupal Ajax 'insert/prepend' command.
  853. *
  854. * The 'insert/prepend' command instructs the client to use jQuery's prepend()
  855. * method to prepend the given HTML content to the inside each element matched
  856. * by the given selector.
  857. *
  858. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  859. * defined in misc/ajax.js.
  860. *
  861. * @param $selector
  862. * A jQuery selector string. If the command is a response to a request from
  863. * an #ajax form element then this value can be NULL.
  864. * @param $html
  865. * The data to use with the jQuery prepend() method.
  866. * @param $settings
  867. * An optional array of settings that will be used for this command only.
  868. *
  869. * @return
  870. * An array suitable for use with the ajax_render() function.
  871. *
  872. * @see http://docs.jquery.com/Manipulation/prepend#content
  873. */
  874. function ajax_command_prepend($selector, $html, $settings = NULL) {
  875. return array(
  876. 'command' => 'insert',
  877. 'method' => 'prepend',
  878. 'selector' => $selector,
  879. 'data' => $html,
  880. 'settings' => $settings,
  881. );
  882. }
  883. /**
  884. * Creates a Drupal Ajax 'insert/append' command.
  885. *
  886. * The 'insert/append' command instructs the client to use jQuery's append()
  887. * method to append the given HTML content to the inside of each element matched
  888. * by the given selector.
  889. *
  890. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  891. * defined in misc/ajax.js.
  892. *
  893. * @param $selector
  894. * A jQuery selector string. If the command is a response to a request from
  895. * an #ajax form element then this value can be NULL.
  896. * @param $html
  897. * The data to use with the jQuery append() method.
  898. * @param $settings
  899. * An optional array of settings that will be used for this command only.
  900. *
  901. * @return
  902. * An array suitable for use with the ajax_render() function.
  903. *
  904. * @see http://docs.jquery.com/Manipulation/append#content
  905. */
  906. function ajax_command_append($selector, $html, $settings = NULL) {
  907. return array(
  908. 'command' => 'insert',
  909. 'method' => 'append',
  910. 'selector' => $selector,
  911. 'data' => $html,
  912. 'settings' => $settings,
  913. );
  914. }
  915. /**
  916. * Creates a Drupal Ajax 'insert/after' command.
  917. *
  918. * The 'insert/after' command instructs the client to use jQuery's after()
  919. * method to insert the given HTML content after each element matched by
  920. * the given selector.
  921. *
  922. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  923. * defined in misc/ajax.js.
  924. *
  925. * @param $selector
  926. * A jQuery selector string. If the command is a response to a request from
  927. * an #ajax form element then this value can be NULL.
  928. * @param $html
  929. * The data to use with the jQuery after() method.
  930. * @param $settings
  931. * An optional array of settings that will be used for this command only.
  932. *
  933. * @return
  934. * An array suitable for use with the ajax_render() function.
  935. *
  936. * @see http://docs.jquery.com/Manipulation/after#content
  937. */
  938. function ajax_command_after($selector, $html, $settings = NULL) {
  939. return array(
  940. 'command' => 'insert',
  941. 'method' => 'after',
  942. 'selector' => $selector,
  943. 'data' => $html,
  944. 'settings' => $settings,
  945. );
  946. }
  947. /**
  948. * Creates a Drupal Ajax 'insert/before' command.
  949. *
  950. * The 'insert/before' command instructs the client to use jQuery's before()
  951. * method to insert the given HTML content before each of elements matched by
  952. * the given selector.
  953. *
  954. * This command is implemented by Drupal.ajax.prototype.commands.insert()
  955. * defined in misc/ajax.js.
  956. *
  957. * @param $selector
  958. * A jQuery selector string. If the command is a response to a request from
  959. * an #ajax form element then this value can be NULL.
  960. * @param $html
  961. * The data to use with the jQuery before() method.
  962. * @param $settings
  963. * An optional array of settings that will be used for this command only.
  964. *
  965. * @return
  966. * An array suitable for use with the ajax_render() function.
  967. *
  968. * @see http://docs.jquery.com/Manipulation/before#content
  969. */
  970. function ajax_command_before($selector, $html, $settings = NULL) {
  971. return array(
  972. 'command' => 'insert',
  973. 'method' => 'before',
  974. 'selector' => $selector,
  975. 'data' => $html,
  976. 'settings' => $settings,
  977. );
  978. }
  979. /**
  980. * Creates a Drupal Ajax 'remove' command.
  981. *
  982. * The 'remove' command instructs the client to use jQuery's remove() method
  983. * to remove each of elements matched by the given selector, and everything
  984. * within them.
  985. *
  986. * This command is implemented by Drupal.ajax.prototype.commands.remove()
  987. * defined in misc/ajax.js.
  988. *
  989. * @param $selector
  990. * A jQuery selector string. If the command is a response to a request from
  991. * an #ajax form element then this value can be NULL.
  992. *
  993. * @return
  994. * An array suitable for use with the ajax_render() function.
  995. *
  996. * @see http://docs.jquery.com/Manipulation/remove#expr
  997. */
  998. function ajax_command_remove($selector) {
  999. return array(
  1000. 'command' => 'remove',
  1001. 'selector' => $selector,
  1002. );
  1003. }
  1004. /**
  1005. * Creates a Drupal Ajax 'changed' command.
  1006. *
  1007. * This command instructs the client to mark each of the elements matched by the
  1008. * given selector as 'ajax-changed'.
  1009. *
  1010. * This command is implemented by Drupal.ajax.prototype.commands.changed()
  1011. * defined in misc/ajax.js.
  1012. *
  1013. * @param $selector
  1014. * A jQuery selector string. If the command is a response to a request from
  1015. * an #ajax form element then this value can be NULL.
  1016. * @param $asterisk
  1017. * An optional CSS selector which must be inside $selector. If specified,
  1018. * an asterisk will be appended to the HTML inside the $asterisk selector.
  1019. *
  1020. * @return
  1021. * An array suitable for use with the ajax_render() function.
  1022. */
  1023. function ajax_command_changed($selector, $asterisk = '') {
  1024. return array(
  1025. 'command' => 'changed',
  1026. 'selector' => $selector,
  1027. 'asterisk' => $asterisk,
  1028. );
  1029. }
  1030. /**
  1031. * Creates a Drupal Ajax 'css' command.
  1032. *
  1033. * The 'css' command will instruct the client to use the jQuery css() method
  1034. * to apply the CSS arguments to elements matched by the given selector.
  1035. *
  1036. * This command is implemented by Drupal.ajax.prototype.commands.css()
  1037. * defined in misc/ajax.js.
  1038. *
  1039. * @param $selector
  1040. * A jQuery selector string. If the command is a response to a request from
  1041. * an #ajax form element then this value can be NULL.
  1042. * @param $argument
  1043. * An array of key/value pairs to set in the CSS for the selector.
  1044. *
  1045. * @return
  1046. * An array suitable for use with the ajax_render() function.
  1047. *
  1048. * @see http://docs.jquery.com/CSS/css#properties
  1049. */
  1050. function ajax_command_css($selector, $argument) {
  1051. return array(
  1052. 'command' => 'css',
  1053. 'selector' => $selector,
  1054. 'argument' => $argument,
  1055. );
  1056. }
  1057. /**
  1058. * Creates a Drupal Ajax 'settings' command.
  1059. *
  1060. * The 'settings' command instructs the client either to use the given array as
  1061. * the settings for ajax-loaded content or to extend Drupal.settings with the
  1062. * given array, depending on the value of the $merge parameter.
  1063. *
  1064. * This command is implemented by Drupal.ajax.prototype.commands.settings()
  1065. * defined in misc/ajax.js.
  1066. *
  1067. * @param $argument
  1068. * An array of key/value pairs to add to the settings. This will be utilized
  1069. * for all commands after this if they do not include their own settings
  1070. * array.
  1071. * @param $merge
  1072. * Whether or not the passed settings in $argument should be merged into the
  1073. * global Drupal.settings on the page. By default (FALSE), the settings that
  1074. * are passed to Drupal.attachBehaviors will not include the global
  1075. * Drupal.settings.
  1076. *
  1077. * @return
  1078. * An array suitable for use with the ajax_render() function.
  1079. */
  1080. function ajax_command_settings($argument, $merge = FALSE) {
  1081. return array(
  1082. 'command' => 'settings',
  1083. 'settings' => $argument,
  1084. 'merge' => $merge,
  1085. );
  1086. }
  1087. /**
  1088. * Creates a Drupal Ajax 'data' command.
  1089. *
  1090. * The 'data' command instructs the client to attach the name=value pair of
  1091. * data to the selector via jQuery's data cache.
  1092. *
  1093. * This command is implemented by Drupal.ajax.prototype.commands.data()
  1094. * defined in misc/ajax.js.
  1095. *
  1096. * @param $selector
  1097. * A jQuery selector string. If the command is a response to a request from
  1098. * an #ajax form element then this value can be NULL.
  1099. * @param $name
  1100. * The name or key (in the key value pair) of the data attached to this
  1101. * selector.
  1102. * @param $value
  1103. * The value of the data. Not just limited to strings can be any format.
  1104. *
  1105. * @return
  1106. * An array suitable for use with the ajax_render() function.
  1107. *
  1108. * @see http://docs.jquery.com/Core/data#namevalue
  1109. */
  1110. function ajax_command_data($selector, $name, $value) {
  1111. return array(
  1112. 'command' => 'data',
  1113. 'selector' => $selector,
  1114. 'name' => $name,
  1115. 'value' => $value,
  1116. );
  1117. }
  1118. /**
  1119. * Creates a Drupal Ajax 'invoke' command.
  1120. *
  1121. * The 'invoke' command will instruct the client to invoke the given jQuery
  1122. * method with the supplied arguments on the elements matched by the given
  1123. * selector. Intended for simple jQuery commands, such as attr(), addClass(),
  1124. * removeClass(), toggleClass(), etc.
  1125. *
  1126. * This command is implemented by Drupal.ajax.prototype.commands.invoke()
  1127. * defined in misc/ajax.js.
  1128. *
  1129. * @param $selector
  1130. * A jQuery selector string. If the command is a response to a request from
  1131. * an #ajax form element then this value can be NULL.
  1132. * @param $method
  1133. * The jQuery method to invoke.
  1134. * @param $arguments
  1135. * (optional) A list of arguments to the jQuery $method, if any.
  1136. *
  1137. * @return
  1138. * An array suitable for use with the ajax_render() function.
  1139. */
  1140. function ajax_command_invoke($selector, $method, array $arguments = array()) {
  1141. return array(
  1142. 'command' => 'invoke',
  1143. 'selector' => $selector,
  1144. 'method' => $method,
  1145. 'arguments' => $arguments,
  1146. );
  1147. }
  1148. /**
  1149. * Creates a Drupal Ajax 'restripe' command.
  1150. *
  1151. * The 'restripe' command instructs the client to restripe a table. This is
  1152. * usually used after a table has been modified by a replace or append command.
  1153. *
  1154. * This command is implemented by Drupal.ajax.prototype.commands.restripe()
  1155. * defined in misc/ajax.js.
  1156. *
  1157. * @param $selector
  1158. * A jQuery selector string.
  1159. *
  1160. * @return
  1161. * An array suitable for use with the ajax_render() function.
  1162. */
  1163. function ajax_command_restripe($selector) {
  1164. return array(
  1165. 'command' => 'restripe',
  1166. 'selector' => $selector,
  1167. );
  1168. }
  1169. /**
  1170. * Creates a Drupal Ajax 'update_build_id' command.
  1171. *
  1172. * This command updates the value of a hidden form_build_id input element on a
  1173. * form. It requires the form passed in to have keys for both the old build ID
  1174. * in #build_id_old and the new build ID in #build_id.
  1175. *
  1176. * The primary use case for this Ajax command is to serve a new build ID to a
  1177. * form served from the cache to an anonymous user, preventing one anonymous
  1178. * user from accessing the form state of another anonymous users on Ajax enabled
  1179. * forms.
  1180. *
  1181. * @param $form
  1182. * The form array representing the form whose build ID should be updated.
  1183. */
  1184. function ajax_command_update_build_id($form) {
  1185. return array(
  1186. 'command' => 'updateBuildId',
  1187. 'old' => $form['#build_id_old'],
  1188. 'new' => $form['#build_id'],
  1189. );
  1190. }