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

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'];
     }