? ajax_documentation.patch
Index: ajax_example/ajax_example.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/examples/ajax_example/ajax_example.module,v
retrieving revision 1.14
diff -u -p -r1.14 ajax_example.module
--- ajax_example/ajax_example.module	20 Jun 2010 19:21:48 -0000	1.14
+++ ajax_example/ajax_example.module	6 Dec 2010 04:40:13 -0000
@@ -13,7 +13,7 @@
  * These examples show basic AJAX concepts.
  *
  * General documentation is available at
- * @link ajax AJAX Framework documentation @endlink and at the
+ * @link ajax/7 AJAX Framework documentation @endlink and at the
  * @link http://drupal.org/node/752056 AJAX Forms handbook page @endlink.
  *
  * The several examples here demonstrate basic AJAX usage.
@@ -22,8 +22,9 @@
 
 /**
  * Set up calls to drupal_get_form() for all our example cases.
- *
+ * 
  * Implements hook_menu().
+ * See @link menu_example_menu Menu Example @endlink for more details on hook_menu.
  */
 function ajax_example_menu() {
   $items = array();
@@ -34,6 +35,8 @@ function ajax_example_menu() {
     'access callback' => TRUE,
     'expanded' => TRUE,
   );
+
+  // Change the description of a form element
   $items['examples/ajax_example/simplest'] = array(
     'title' => 'Simplest AJAX Example',
     'page callback' => 'drupal_get_form',
@@ -41,7 +44,7 @@ function ajax_example_menu() {
     'access callback' => TRUE,
     'weight' => 0,
   );
-  // Automatically generate checkboxes
+  // Generate a changing number of checkboxes
   $items['examples/ajax_example/autocheckboxes'] = array(
     'title' => 'Generate checkboxes',
     'page callback' => 'drupal_get_form',
@@ -49,8 +52,7 @@ function ajax_example_menu() {
     'access callback' => TRUE,
     'weight' => 1,
   );
-
-    // Automatically generate textfields
+  // Generate different textfields based on form state
   $items['examples/ajax_example/autotextfields'] = array(
     'title' => 'Generate textfields',
     'page callback' => 'drupal_get_form',
@@ -59,6 +61,7 @@ function ajax_example_menu() {
     'weight' => 2,
   );
 
+  // Submit a form without a page reload
   $items['examples/ajax_example/submit_driven_ajax'] = array(
     'title' => 'Submit-driven AJAX',
     'page callback' => 'drupal_get_form',
@@ -67,6 +70,7 @@ function ajax_example_menu() {
     'weight' => 3,
   );
 
+  // Repopulate a dropdown based on form state
   $items['examples/ajax_example/dependent_dropdown'] = array(
     'title' => 'Dependent dropdown',
     'page callback' => 'drupal_get_form',
@@ -74,6 +78,8 @@ function ajax_example_menu() {
     'access callback' => TRUE,
     'weight' => 4,
   );
+  // Repopulate a dropdown, but this time with graceful degredation
+  // See ajax_example_graceful_degradation.inc
   $items['examples/ajax_example/dependent_dropdown_degrades'] = array(
     'title' => 'Dependent dropdown (with graceful degradation)',
     'page callback' => 'drupal_get_form',
@@ -82,6 +88,7 @@ function ajax_example_menu() {
     'weight' => 5,
     'file' => 'ajax_example_graceful_degradation.inc',
   );
+  // The above example as it appears to users with no javascript
   $items['examples/ajax_example/dependent_dropdown_degrades_no_js'] = array(
     'title' => 'Dependent dropdown with javascript off',
     'page callback' => 'drupal_get_form',
@@ -91,24 +98,8 @@ function ajax_example_menu() {
     'weight' => 5,
   );
 
-  $items['examples/ajax_example/dynamic_sections'] = array(
-    'title' => 'Dynamic Sections (with graceful degradation)',
-    'page callback' => 'drupal_get_form',
-    'page arguments' => array('ajax_example_dynamic_sections'),
-    'access callback' => TRUE,
-    'weight' => 6,
-    'file' => 'ajax_example_graceful_degradation.inc',
-  );
-  $items['ajax_example/dynamic_sections_no_js'] = array(
-    'title' => 'Dynamic Sections w/JS turned off',
-    'page callback' => 'drupal_get_form',
-    'page arguments' => array('ajax_example_dynamic_sections', TRUE),
-    'access callback' => TRUE,
-    'weight' => 6,
-    'file' => 'ajax_example_graceful_degradation.inc',
-  );
-
-
+  // A classic multi-step wizard, but with no page reloads
+  // See ajax_example_graceful_degradation.inc
   $items['examples/ajax_example/wizard'] = array(
     'title' => 'Wizard (with graceful degradation)',
     'page callback' => 'drupal_get_form',
@@ -117,6 +108,7 @@ function ajax_example_menu() {
     'file' => 'ajax_example_graceful_degradation.inc',
     'weight' => 7,
   );
+  // The above example as it appears to users with no javascript
   $items['examples/ajax_example/wizard_no_js'] = array(
     'title' => 'Wizard w/JS turned off',
     'page callback' => 'drupal_get_form',
@@ -126,6 +118,8 @@ function ajax_example_menu() {
     'weight' => 7,
   );
 
+  // Add more button that creates additional form elements
+  // See ajax_example_graceful_degradation.inc
   $items['examples/ajax_example/add_more'] = array(
     'title' => 'Add-more button (with graceful degradation)',
     'page callback' => 'drupal_get_form',
@@ -134,6 +128,7 @@ function ajax_example_menu() {
     'file' => 'ajax_example_graceful_degradation.inc',
     'weight' => 8,
   );
+  // The above example as it appears to users with no javascript
   $items['examples/ajax_example/add_more_no_js'] = array(
     'title' => 'Add-more button w/JS turned off',
     'page callback' => 'drupal_get_form',
@@ -143,6 +138,8 @@ function ajax_example_menu() {
     'weight' => 8,
   );
 
+  // Use AJAX framework commands outside of the #ajax form property
+  // See ajax_example_advanced.inc
   $items['examples/ajax_example/advanced_commands'] = array(
     'title' => 'AJAX framework commands',
     'page callback' => 'drupal_get_form',
@@ -152,6 +149,8 @@ function ajax_example_menu() {
     'weight' => 10,
   );
 
+  // Use the AJAX framework outside the context of a form
+  // See ajax_example_misc.inc
   $items['examples/ajax_example/ajax_link'] = array(
     'title' => 'Ajax Link',
     'page callback' => 'ajax_example_render_link',
@@ -159,7 +158,7 @@ function ajax_example_menu() {
     'file' => 'ajax_example_misc.inc',
     'weight' => 9,
   );
-
+  // A menu callback is required when using ajax outside of the Form API
   $items['ajax_link_callback'] = array(
     'page callback' => 'ajax_link_response',
     'access callback' => 'user_access',
@@ -184,6 +183,7 @@ function ajax_example_intro() {
 /**
  * Simple form whose ajax-enabled 'changethis' member causes a text change
  * in the description of the 'replace_textfield' member.
+ * See @link http://drupal.org/node/262422 Form API Tutorial @endlink
  */
 function ajax_example_simplest($form, &$form_state) {
   $form = array();
@@ -196,35 +196,40 @@ function ajax_example_simplest($form, &$
       'three' => 'three',
     ),
     '#ajax' => array(
+      // #ajax has to required keys: callback and wrapper
+      // 'callback' is a function that will be called when this element changes
       'callback' => 'ajax_example_simplest_callback',
+      // 'wrapper' is the DOM id of the page element that will be replaced
       'wrapper' => 'replace_textfield_div',
+      // There are also two optional keys - see ajax_example_autocheckboxes
+      // below for details on 'method' and 'effect'
      ),
   );
 
-  // This entire form element will be replaced with an updated value.
-  // However, it has to have the prefix/suffix to work right, as the entire
-  // div is replaced.
-  // In this example, the description is dynamically updated during form
-  // rebuild.
-
   $form['replace_textfield'] = array(
     '#type' => 'textfield',
     '#title' => t("Why"),
+    // Since we set 'wrapper'
     '#prefix' => '<div id="replace_textfield_div">',
     '#suffix' => '</div>',
   );
+  // Since we set 'wrapper' to replace_textfield_div above, this entire form
+  // element will be replaced whenever 'changethis' is updated.
 
+  // An AJAX request calls the form builder function for every change.
+  // We can change how we build the form based on $form_state.
   if (!empty($form_state['values']['changethis'])) {
     $form['replace_textfield']['#description'] = t("Say why you chose") .  " '{$form_state['values']['changethis']}'";
   }
   return $form;
 }
+
 /**
  * Callback for ajax_example_simplest.
  *
- * The form item 'replace_textfield' has already been processed and changed
- * when the form was submitted and rebuilt during the AJAX call, so now
- * we just return the piece of the form that changed.
+ * On an ajax submit, the form builder function is called again, then the $form
+ * and $form_state is passed to this callback function so it can select which
+ * portion of the form to send on to the client.
  */
 function ajax_example_simplest_callback($form, $form_state) {
   // The form has already been submitted and updated. We can return the replaced
@@ -232,7 +237,6 @@ function ajax_example_simplest_callback(
   return $form['replace_textfield'];
 }
 
-
 /**
  * AJAX-enabled select element causes replacement of a set of checkboxes
  * based on the selection.
Index: ajax_example/ajax_example_graceful_degradation.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/examples/ajax_example/ajax_example_graceful_degradation.inc,v
retrieving revision 1.9
diff -u -p -r1.9 ajax_example_graceful_degradation.inc
--- ajax_example/ajax_example_graceful_degradation.inc	11 Aug 2010 23:13:15 -0000	1.9
+++ ajax_example/ajax_example_graceful_degradation.inc	6 Dec 2010 04:40:13 -0000
@@ -161,183 +161,6 @@ function ajax_example_dependent_dropdown
   return $form['dropdown_second_fieldset']['dropdown_second'];
 }
 
-
-
-/**
- * Example of a form with portions dynamically enabled or disabled, but
- * with graceful degradation in the case of no javascript.
- *
- * The idea here is that certain parts of the form don't need to be displayed
- * unless a given option is selected, but then they should be displayed and
- * configured.
- *
- * The third $no_js_use argument is strictly for demonstrating operation
- * without javascript, without making the user/developer turn off javascript.
- *
- * @ingroup ajax_examples
- * @ingroup ajax_degradation_examples
- */
-
-function ajax_example_dynamic_sections($form, &$form_state, $no_js_use = FALSE) {
-
-  // Attach the CSS and JS we need to show this with and without javascript.
-  // Without javascript we need an extra "Choose" button, and this is
-  // hidden when we have javascript enabled.
-
-  $form['#attached']['css'] = array(
-    drupal_get_path('module', 'ajax_example') . '/ajax_example.css',
-  );
-  $form['#attached']['js'] = array(
-    drupal_get_path('module', 'ajax_example') . '/ajax_example.js',
-  );
-  $form['description'] = array(
-    '#type' => 'markup',
-    '#markup' => '<div>' . t('This example demonstrates a form which dynamically creates various sections based on the configuration in the form.
-      It deliberately allows graceful degradation to a non-javascript environment.
-      In a javascript environment, the "Choose" button next to the select control
-      if displayed; in a non-js environment it is hidden by the module CSS.
-      <br/><br/>The basic idea here is that the form is built up based on
-      the selection in the question_type_select field, and it is built the same
-      whether we are in a javascript/AJAX environment or not.
-      <br/><br/>
-      Try the <a href="!ajax_link">AJAX version</a> and the <a href="!non_ajax_link">simulated-non-AJAX version</a>.
-    ', array('!ajax_link' => url('ajax_example/dynamic_sections'), '!non_ajax_link' => url('ajax_example/dynamic_sections_no_js') )) . '</div>',
-  );
-
-  $form['question_type_select'] = array(
-    '#type' => 'select',
-    '#title' => t('Question style'),
-    '#options' => drupal_map_assoc(array(t('Choose question style'), t('Multiple Choice'), t('True/False'), t('Fill-in-the-blanks'))),
-    '#ajax' => array(
-      'wrapper' => 'questions-fieldset-wrapper',
-      'callback' => 'ajax_example_dynamic_sections_select_callback',
-    ),
-  );
-  // The CSS for this module hides this next button if JS is enabled.
-  $form['question_type_submit'] = array(
-    '#type' => 'submit',
-    '#value' => t('Choose'),
-    '#attributes' => array('class' => array('next-button')),
-    '#limit_validation_errors' => array(),  // No need to validate when submitting this.
-    '#validate' => array(),
-  );
-
-  // This simply allows us to demonstrate no-javascript use without
-  // actually turning off javascript in the browser. Removing the #ajax
-  // element turns off AJAX behaviors on that element and as a result
-  // ajax.js doesn't get loaded.
-
-  if ($no_js_use) {
-    // Remove the #ajax from the above, so ajax.js won't be loaded.
-    unset($form['question_type_select']['#ajax']);
-  }
-
-  // This fieldset just serves as a container for the part of the form
-  // that gets rebuilt.
-  $form['questions_fieldset'] = array(
-    '#type' => 'fieldset',
-
-    // These provide the wrapper referred to in #ajax['wrapper'] above.
-    '#prefix' => '<div id="questions-fieldset-wrapper">',
-    '#suffix' => '</div>',
-  );
-  if (!empty($form_state['values']['question_type_select'])) {
-
-    $form['questions_fieldset']['question'] = array(
-      '#markup' => t('Who was the first president of the U.S.?'),
-    );
-    $question_type = $form_state['values']['question_type_select'];
-
-    switch ($question_type) {
-      case t('Multiple Choice'):
-        $form['questions_fieldset']['question'] = array(
-          '#type' => 'radios',
-          '#title' => t('Who was the first president of the United States'),
-          '#options' => drupal_map_assoc(array(t('George Bush'), t('Adam McGuire'), t('Abraham Lincoln'), t('George Washington'))),
-        );
-        break;
-
-      case t('True/False'):
-        $form['questions_fieldset']['question'] = array(
-          '#type' => 'radios',
-          '#title' => t('Was George Washington the first president of the United States?'),
-          '#options' => array(t('George Washington') => t("True"), 0 => t("False")),
-          '#description' => t('Click "True" if you think George Washington was the first president of the United States.'),
-        );
-        break;
-
-      case t('Fill-in-the-blanks'):
-        $form['questions_fieldset']['question'] = array(
-          '#type' => 'textfield',
-          '#title' => t('Who was the first president of the United States'),
-          '#description' => t('Please type the correct answer to the question.'),
-        );
-        break;
-
-    }
-
-    $form['questions_fieldset']['submit'] = array(
-      '#type' => 'submit',
-      '#value' => t('Submit your answer'),
-    );
-  }
-
-  return $form;
-}
-
-/**
- * Validation function for ajax_example_dynamic_sections().
- *
- */
-function ajax_example_dynamic_sections_validate($form, &$form_state) {
-  $answer = $form_state['values']['question'];
-  if ($answer !== t('George Washington')) {
-    form_set_error('question', t('Wrong answer. Try again. (Hint: The right answer is "George Washington".)'));
-  }
-}
-
-/**
- * Submit function for ajax_example_dynamic_sections().
- */
-function ajax_example_dynamic_sections_submit($form, &$form_state) {
-  // This is only executed when a button is pressed, not when the AJAXified
-  // select is changed.
-  // Now handle the case of the next, previous, and submit buttons.
-  // only submit will result in actual submission, all others rebuild.
-  switch($form_state['triggering_element']['#value']) {
-    case t('Submit your answer'): // Submit: We're done.
-      $form_state['rebuild'] = FALSE;
-      $answer = $form_state['values']['question'];
-
-      // Special handling for the checkbox.
-      if ($answer == 1 && $form['questions_fieldset']['question']['#type'] == 'checkbox') {
-        $answer = $form['questions_fieldset']['question']['#title'];
-      }
-      if ($answer === t('George Washington')) {
-        drupal_set_message(t('You got the right answer: @answer', array('@answer' => $answer)));
-      }
-      else {
-        drupal_set_message(t('Sorry, your answer (@answer) is wrong', array('@answer' => $answer)));
-      }
-      $form_state['rebuild'] = FALSE;
-      return;
-  }
-
-  // Any other form element will cause rebuild of the form and present
-  // it again.
-  $form_state['rebuild'] = TRUE;
-}
-
-/**
- * Callback for the select element.
- *
- * This just selects and returns the questions_fieldset.
- */
-function ajax_example_dynamic_sections_select_callback($form, $form_state) {
-  return $form['questions_fieldset'];
-}
-
-
 /**
  * This example is a classic wizard, where a different and sequential form
  * is presented on each step of the form.