Commit 0fa98a7a authored by Dries's avatar Dries

- Patch #610068 by katbailey, rfay: improved phpDoc.

parent 4575dbaa
......@@ -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'];
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment