diff options
author | Dries Buytaert <dries@buytaert.net> | 2010-01-27 11:19:11 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2010-01-27 11:19:11 +0000 |
commit | 0fa98a7a35eee060b996150d22d47937cee8591d (patch) | |
tree | b367983b95ff0067779e69ce509709e6094a264b /includes/ajax.inc | |
parent | 4575dbaa572db6c32e8e9fe319d454af4f106afd (diff) | |
download | brdo-0fa98a7a35eee060b996150d22d47937cee8591d.tar.gz brdo-0fa98a7a35eee060b996150d22d47937cee8591d.tar.bz2 |
- Patch #610068 by katbailey, rfay: improved phpDoc.
Diffstat (limited to 'includes/ajax.inc')
-rw-r--r-- | includes/ajax.inc | 122 |
1 files changed, 92 insertions, 30 deletions
diff --git a/includes/ajax.inc b/includes/ajax.inc index 33eab0ad5..2c5f3a9cf 100644 --- a/includes/ajax.inc +++ b/includes/ajax.inc @@ -19,28 +19,97 @@ * instruct JavaScript to perform actions on the client browser. When using * forms, it can be used with the #ajax property. * The #ajax property can be used to bind events to the AJAX framework. By - * default, #ajax uses 'system/ajax' as path, along with its defined page - * callback. However, you may optionally specify a different path to request or - * a different callback function to invoke, which can return updated HTML or can - * also return a richer set of AJAX framework commands. + * default, #ajax uses 'system/ajax' as its path for submission and thus calls + * @link ajax_form_callback ajax_form_callback @endlink and a defined + * #ajax['callback'] function. However, you may optionally specify a different + * path to request or a different callback function to invoke, which can return + * updated HTML or can also return a richer set of + * @link ajax_commands AJAX framework commands @endlink. + * + * Standard form handling is as follows: + * - A form element has a #ajax member. + * - On the specified element, AJAX processing is triggered by a change to + * that element. + * - The form is submitted and rebuilt. + * - The function named by #ajax['callback'] is called, which returns content + * or an array of AJAX framework commands. + * - The content returned by the callback replaces the div on the page + * referenced by #ajax['wrapper']. + * + * A simple example of basic AJAX use from the + * @link http://drupal.org/project/examples Examples module @endlink follows: + * @code + * function main_page() { + * return drupal_get_form('ajax_example_simplest'); + * } + * + * function ajax_example_simplest($form, &$form_state) { + * $form = array(); + * $form['changethis'] = array( + * '#type' => 'select', + * '#options' => array( + * 'one' => 'one', + * 'two' => 'two', + * 'three' => 'three', + * ), + * '#ajax' => array( + * 'callback' => 'ajax_example_simplest_callback', + * 'wrapper' => 'replace_textfield_div', + * ), + * ); + + * // This entire form element will be replaced with an updated value. + * $form['replace_textfield'] = array( + * '#type' => 'textfield', + * '#title' => t("The default value will be changed"), + * '#description' => t("Say something about why you chose") . "'" . + * (!empty($form_state['values']['changethis']) + * ? $form_state['values']['changethis'] : t("Not changed yet")) . "'", + * '#prefix' => '<div id="replace_textfield_div">', + * '#suffix' => '</div>', + * ); + * return $form; + * } + * + * function ajax_example_simplest_callback($form, $form_state) { + * // The form has already been submitted and updated. We can return the replaced + * // item as it is. + * return $form['replace_textfield']; + * } + * @endcode * - * See @link ajax_commands AJAX framework commands @endlink + * In the above example, the 'changethis' element is AJAX-enabled. The default + * #ajax['event'] is 'change', so when the 'changethis' element changes, + * an AJAX call is made. The form is submitted and reprocessed, and then the + * callback is called. In this case, the form has been automatically + * built changing $form['replace_textfield']['#description'], so the callback + * just returns that part of the form. * - * To implement AJAX handling in a normal form, add '#ajax' to the form + * To implement AJAX handling in a form, add '#ajax' to the form * definition of a field. That field will trigger an AJAX event when it is * clicked (or changed, depending on the kind of field). #ajax supports * the following parameters (either 'path' or 'callback' is required at least): - * - #ajax['path']: The menu path to use for the request. This path should map + * - #ajax['callback']: The callback to invoke to handle the server side of the + * AJAX event, which will receive a $form and $form_state as arguments, and + * returns a renderable array (most often a form or form fragment), an HTML + * string, or an array of AJAX commands. If returning a renderable array or + * a string, the value will replace the original element named in + * #ajax['wrapper'], and + * theme_status_messages() + * will be prepended to that + * element. (If the status messages are not wanted, return an array + * of AJAX commands instead.) + * #ajax['wrapper']. If an array of AJAX commands is returned, it will be + * executed by the calling code. + * - #ajax['path']: The menu path to use for the request. This is often omitted + * and the default is used. This path should map * to a menu page callback that returns data using ajax_render(). Defaults to - * 'system/ajax', which invokes ajax_form_callback(). If you use a custom + * 'system/ajax', which invokes ajax_form_callback(), eventually calling + * the function named in #ajax['callback']. If you use a custom * path, you must set up the menu entry and handle the entire callback in your * own code. - * - #ajax['callback']: The callback to invoke to handle the server side of the - * AJAX event, which will receive a $form and $form_state as arguments, and - * should return a HTML string to replace the original element named in - * #ajax['wrapper'] or a list of AJAX commands. - * - #ajax['wrapper']: The CSS ID of the area to be replaced by the HTML - * returned by the #ajax['callback'] function. The HTML string returned from + * - #ajax['wrapper']: The CSS ID of the area to be replaced by the content + * returned by the #ajax['callback'] function. The content returned from * the callback will replace the entire element named by #ajax['wrapper']. * The wrapper is usually created using #prefix and #suffix properties in the * form. Note that this is the wrapper ID, not a CSS selector. So to replace @@ -83,10 +152,11 @@ * be converted to a JSON object and returned to the client, which will then * iterate over the array and process it like a macro language. * - * Each command is an object. $object->command is the type of command and will - * be used to find the method (it will correlate directly to a method in - * the Drupal.ajax[command] space). The object may contain any other data that - * the command needs to process. + * Each command item is an associative array which will be converted to a command + * object on the JavaScript side. $command_item['command'] is the type of + * command, e.g. 'alert' or 'replace', and will correspond to a method in the + * Drupal.ajax[command] space. The command array may contain any other data + * that the command needs to process, e.g. 'method', 'selector', 'settings', etc. * * Commands are usually created with a couple of helper functions, so they * look like this: @@ -101,17 +171,9 @@ * ajax_render($commands); * @endcode * - * When the system's default #ajax['path'] is used, the invoked callback - * function can either return a HTML string or an AJAX command structure. - * - * In case an AJAX callback returns a HTML string instead of an AJAX command - * structure, ajax_form_callback() automatically replaces the original container - * by using the ajax_command_replace() command and additionally prepends the - * returned output with any status messages. - * - * When returning an AJAX command structure, it is likely that any status - * messages shall be output with the given HTML. To achieve the same result - * using an AJAX command structure, the AJAX callback may use the following: + * When returning an AJAX command array, it is often useful to have + * status messages rendered along with other tasks in the command array. + * In that case the the AJAX commands array may be constructed like this: * @code * $commands = array(); * $commands[] = ajax_command_replace(NULL, $output); @@ -328,7 +390,7 @@ function ajax_deliver($page_callback_result) { } elseif (is_array($page_callback_result) && isset($page_callback_result['#type']) && ($page_callback_result['#type'] == 'ajax_commands')) { // Complex AJAX callbacks can return a result that contains a specific - // set of commands to send to the browser. + // set of commands to send to the browser. if (isset($page_callback_result['#ajax_commands'])) { $commands = $page_callback_result['#ajax_commands']; } |