ajax_example_graceful_degradation.inc

<?php

/**
 * @file
 * Demonstrations of AJAX with graceful degradation.
 */

/**
 * @defgroup ajax_degradation_example Example: AJAX Graceful Degradation
 * @ingroup examples
 * @{
 * These examples show AJAX with graceful degradation when Javascript is not
 * available.
 *
 * In each of these the key idea is that the form is rebuilt different ways
 * depending on form input. In order to accomplish that, the formbuilder
 * function is in charge of almost all logic.
 */

/**
 * Dropdown form based on previous choices.
 *
 * A form with a dropdown whose options are dependent on a choice made in a
 * previous dropdown.
 *
 * On changing the first dropdown, the options in the second
 * are updated. Gracefully degrades if no javascript.
 *
 * A bit of CSS and javascript is required. The CSS hides the "add more" button
 * if javascript is not enabled. The Javascript snippet is really only used
 * to enable us to present the form in degraded mode without forcing the user
 * to turn off Javascript.  Both of these are loaded by using the
 * #attached FAPI property, so it is a good example of how to use that.
 *
 * The extra argument $no_js_use is here only to allow presentation of this
 * form as if Javascript were not enabled. ajax_example_menu() provides two
 * ways to call this form, one normal ($no_js_use = FALSE) and one simulating
 * Javascript disabled ($no_js_use = TRUE).
 */
function ajax_example_dependent_dropdown_degrades($form, &$form_state, $no_js_use = FALSE) {

  // Get the list of options to populate the first dropdown.
  $options_first = _ajax_example_get_first_dropdown_options();

  // If we have a value for the first dropdown from $form_state['values'] we use
  // this both as the default value for the first dropdown and also as a
  // parameter to pass to the function that retrieves the options for the
  // second dropdown.
  $selected = isset($form_state['values']['dropdown_first']) ? $form_state['values']['dropdown_first'] : key($options_first);

  // 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['dropdown_first_fieldset'] = array(
    '#type' => 'fieldset',
  );
  $form['dropdown_first_fieldset']['dropdown_first'] = array(
    '#type' => 'select',
    '#title' => 'Instrument Type',
    '#options' => $options_first,
    '#attributes' => array(
      'class' => array(
        'enabled-for-ajax',
      ),
    ),
    // The '#ajax' property allows us to bind a callback to the server whenever
    // this form element changes. See ajax_example_autocheckboxes and
    // ajax_example_dependent_dropdown in ajax_example.module for more details.
    '#ajax' => array(
      'callback' => 'ajax_example_dependent_dropdown_degrades_first_callback',
      'wrapper' => 'dropdown-second-replace',
    ),
  );

  // 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. This is for demonstration purposes only.
  if ($no_js_use) {
    unset($form['dropdown_first_fieldset']['dropdown_first']['#ajax']);
  }

  // Since we don't know if the user has js or not, we always need to output
  // this element, then hide it with with css if javascript is enabled.
  $form['dropdown_first_fieldset']['continue_to_second'] = array(
    '#type' => 'submit',
    '#value' => t('Choose'),
    '#attributes' => array(
      'class' => array(
        'next-button',
      ),
    ),
  );
  $form['dropdown_second_fieldset'] = array(
    '#type' => 'fieldset',
  );
  $form['dropdown_second_fieldset']['dropdown_second'] = array(
    '#type' => 'select',
    '#title' => $options_first[$selected] . ' ' . t('Instruments'),
    '#prefix' => '<div id="dropdown-second-replace">',
    '#suffix' => '</div>',
    '#attributes' => array(
      'class' => array(
        'enabled-for-ajax',
      ),
    ),
    // When the form is rebuilt during processing (either AJAX or multistep),
    // the $selected variable will now have the new value and so the options
    // will change.
    '#options' => _ajax_example_get_second_dropdown_options($selected),
  );
  $form['dropdown_second_fieldset']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('OK'),
    // This class allows attached js file to override the disabled attribute,
    // since it's not necessary in ajax-enabled form.
    '#attributes' => array(
      'class' => array(
        'enabled-for-ajax',
      ),
    ),
  );

  // Disable dropdown_second if a selection has not been made on dropdown_first.
  if (empty($form_state['values']['dropdown_first'])) {
    $form['dropdown_second_fieldset']['dropdown_second']['#disabled'] = TRUE;
    $form['dropdown_second_fieldset']['dropdown_second']['#description'] = t('You must make your choice on the first dropdown before changing this second one.');
    $form['dropdown_second_fieldset']['submit']['#disabled'] = TRUE;
  }
  return $form;
}

/**
 * Submit function for ajax_example_dependent_dropdown_degrades().
 */
function ajax_example_dependent_dropdown_degrades_submit($form, &$form_state) {

  // 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('OK'):

      // Submit: We're done.
      drupal_set_message(t('Your values have been submitted. dropdown_first=@first, dropdown_second=@second', array(
        '@first' => $form_state['values']['dropdown_first'],
        '@second' => $form_state['values']['dropdown_second'],
      )));
      return;
  }

  // 'Choose' or anything else will cause rebuild of the form and present
  // it again.
  $form_state['rebuild'] = TRUE;
}

/**
 * Selects just the second dropdown to be returned for re-rendering.
 *
 * @return array
 *   Renderable array (the second dropdown).
 */
function ajax_example_dependent_dropdown_degrades_first_callback($form, $form_state) {
  return $form['dropdown_second_fieldset']['dropdown_second'];
}

/**
 * Dynamically-enabled form with graceful no-JS degradation.
 *
 * 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.
 */
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 non-javascript environment, the "Choose" button next to the select control
      is displayed; in a javascript 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('examples/ajax_example/dynamic_sections'),
      '!non_ajax_link' => url('examples/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',
      ),
    ),
    // No need to validate when submitting this.
    '#limit_validation_errors' => array(),
    '#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,
        )));
      }
      return;

    // Any other form element will cause rebuild of the form and present
    // it again.
    case t('Choose'):
      $form_state['values']['question_type_select'] = $form_state['input']['question_type_select'];

    // Fall through.
    default:
      $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'];
}

/**
 * Wizard form.
 *
 * This example is a classic wizard, where a different and sequential form
 * is presented on each step of the form.
 *
 * In the AJAX version, the form is replaced for each wizard section. In the
 * multistep version, it causes a new page load.
 *
 * @param array $form
 *   Form API form.
 * @param array $form_state
 *   Form API form.
 * @param bool $no_js_use
 *   Used for this demonstration only. If true means that the form should be
 *   built using a simulated no-javascript approach (ajax.js will not be
 *   loaded.)
 *
 * @return array
 *   Form array.
 */
function ajax_example_wizard($form, &$form_state, $no_js_use = FALSE) {

  // Provide a wrapper around the entire form, since we'll replace the whole
  // thing with each submit.
  $form['#prefix'] = '<div id="wizard-form-wrapper">';
  $form['#suffix'] = '</div>';

  // We want to deal with hierarchical form values.
  $form['#tree'] = TRUE;
  $form['description'] = array(
    '#markup' => '<div>' . t('This example is a step-by-step wizard. The <a href="!ajax">AJAX version</a> does it without page reloads; the <a href="!multistep">multistep version</a> is the same code but simulates a non-javascript environment, showing it with page reloads.', array(
      '!ajax' => url('examples/ajax_example/wizard'),
      '!multistep' => url('examples/ajax_example/wizard_no_js'),
    )) . '</div>',
  );

  // $form_state['storage'] has no specific drupal meaning, but it is
  // traditional to keep variables for multistep forms there.
  $step = empty($form_state['storage']['step']) ? 1 : $form_state['storage']['step'];
  $form_state['storage']['step'] = $step;
  switch ($step) {
    case 1:
      $form['step1'] = array(
        '#type' => 'fieldset',
        '#title' => t('Step 1: Personal details'),
      );
      $form['step1']['name'] = array(
        '#type' => 'textfield',
        '#title' => t('Your name'),
        '#default_value' => empty($form_state['values']['step1']['name']) ? '' : $form_state['values']['step1']['name'],
        '#required' => TRUE,
      );
      break;
    case 2:
      $form['step2'] = array(
        '#type' => 'fieldset',
        '#title' => t('Step 2: Street address info'),
      );
      $form['step2']['address'] = array(
        '#type' => 'textfield',
        '#title' => t('Your street address'),
        '#default_value' => empty($form_state['values']['step2']['address']) ? '' : $form_state['values']['step2']['address'],
        '#required' => TRUE,
      );
      break;
    case 3:
      $form['step3'] = array(
        '#type' => 'fieldset',
        '#title' => t('Step 3: City info'),
      );
      $form['step3']['city'] = array(
        '#type' => 'textfield',
        '#title' => t('Your city'),
        '#default_value' => empty($form_state['values']['step3']['city']) ? '' : $form_state['values']['step3']['city'],
        '#required' => TRUE,
      );
      break;
  }
  if ($step == 3) {
    $form['submit'] = array(
      '#type' => 'submit',
      '#value' => t("Submit your information"),
    );
  }
  if ($step < 3) {
    $form['next'] = array(
      '#type' => 'submit',
      '#value' => t('Next step'),
      '#ajax' => array(
        'wrapper' => 'wizard-form-wrapper',
        'callback' => 'ajax_example_wizard_callback',
      ),
    );
  }
  if ($step > 1) {
    $form['prev'] = array(
      '#type' => 'submit',
      '#value' => t("Previous step"),
      // Since all info will be discarded, don't validate on 'prev'.
      '#limit_validation_errors' => array(),
      // #submit is required to use #limit_validation_errors
      '#submit' => array(
        'ajax_example_wizard_submit',
      ),
      '#ajax' => array(
        'wrapper' => 'wizard-form-wrapper',
        'callback' => 'ajax_example_wizard_callback',
      ),
    );
  }

  // 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.
  // For demonstration only! You don't need this.
  if ($no_js_use) {

    // Remove the #ajax from the above, so ajax.js won't be loaded.
    // For demonstration only.
    unset($form['next']['#ajax']);
    unset($form['prev']['#ajax']);
  }
  return $form;
}

/**
 * Wizard callback function.
 *
 * @param array $form
 *   Form API form.
 * @param array $form_state
 *   Form API form.
 *
 * @return array
 *   Form array.
 */
function ajax_example_wizard_callback($form, $form_state) {
  return $form;
}

/**
 * Submit function for ajax_example_wizard.
 *
 * In AJAX this is only submitted when the final submit button is clicked,
 * but in the non-javascript situation, it is submitted with every
 * button click.
 */
function ajax_example_wizard_submit($form, &$form_state) {

  // Save away the current information.
  $current_step = 'step' . $form_state['storage']['step'];
  if (!empty($form_state['values'][$current_step])) {
    $form_state['storage']['values'][$current_step] = $form_state['values'][$current_step];
  }

  // Increment or decrement the step as needed. Recover values if they exist.
  if ($form_state['triggering_element']['#value'] == t('Next step')) {
    $form_state['storage']['step']++;

    // If values have already been entered for this step, recover them from
    // $form_state['storage'] to pre-populate them.
    $step_name = 'step' . $form_state['storage']['step'];
    if (!empty($form_state['storage']['values'][$step_name])) {
      $form_state['values'][$step_name] = $form_state['storage']['values'][$step_name];
    }
  }
  if ($form_state['triggering_element']['#value'] == t('Previous step')) {
    $form_state['storage']['step']--;

    // Recover our values from $form_state['storage'] to pre-populate them.
    $step_name = 'step' . $form_state['storage']['step'];
    $form_state['values'][$step_name] = $form_state['storage']['values'][$step_name];
  }

  // If they're done, submit.
  if ($form_state['triggering_element']['#value'] == t('Submit your information')) {
    $value_message = t('Your information has been submitted:') . ' ';
    foreach ($form_state['storage']['values'] as $step => $values) {
      $value_message .= "{$step}: ";
      foreach ($values as $key => $value) {
        $value_message .= "{$key}={$value}, ";
      }
    }
    drupal_set_message($value_message);
    $form_state['rebuild'] = FALSE;
    return;
  }

  // Otherwise, we still have work to do.
  $form_state['rebuild'] = TRUE;
}

/**
 * Form with 'add more' and 'remove' buttons.
 *
 * This example shows a button to "add more" - add another textfield, and
 * the corresponding "remove" button.
 *
 * It works equivalently with javascript or not, and does the same basic steps
 * either way.
 *
 * The basic idea is that we build the form based on the setting of
 * $form_state['num_names']. The custom submit functions for the "add-one"
 * and "remove-one" buttons increment and decrement $form_state['num_names']
 * and then force a rebuild of the form.
 *
 * The $no_js_use argument is simply for demonstration: When set, it prevents
 * '#ajax' from being set, thus making the example behave as if javascript
 * were disabled in the browser.
 */
function ajax_example_add_more($form, &$form_state, $no_js_use = FALSE) {
  $form['description'] = array(
    '#markup' => '<div>' . t('This example shows an add-more and a remove-last button. The <a href="!ajax">AJAX version</a> does it without page reloads; the <a href="!multistep">non-js version</a> is the same code but simulates a non-javascript environment, showing it with page reloads.', array(
      '!ajax' => url('examples/ajax_example/add_more'),
      '!multistep' => url('examples/ajax_example/add_more_no_js'),
    )) . '</div>',
  );

  // Because we have many fields with the same values, we have to set
  // #tree to be able to access them.
  $form['#tree'] = TRUE;
  $form['names_fieldset'] = array(
    '#type' => 'fieldset',
    '#title' => t('People coming to the picnic'),
    // Set up the wrapper so that AJAX will be able to replace the fieldset.
    '#prefix' => '<div id="names-fieldset-wrapper">',
    '#suffix' => '</div>',
  );

  // Build the fieldset with the proper number of names. We'll use
  // $form_state['num_names'] to determine the number of textfields to build.
  if (empty($form_state['num_names'])) {
    $form_state['num_names'] = 1;
  }
  for ($i = 0; $i < $form_state['num_names']; $i++) {
    $form['names_fieldset']['name'][$i] = array(
      '#type' => 'textfield',
      '#title' => t('Name'),
    );
  }
  $form['names_fieldset']['add_name'] = array(
    '#type' => 'submit',
    '#value' => t('Add one more'),
    '#submit' => array(
      'ajax_example_add_more_add_one',
    ),
    // See the examples in ajax_example.module for more details on the
    // properties of #ajax.
    '#ajax' => array(
      'callback' => 'ajax_example_add_more_callback',
      'wrapper' => 'names-fieldset-wrapper',
    ),
  );
  if ($form_state['num_names'] > 1) {
    $form['names_fieldset']['remove_name'] = array(
      '#type' => 'submit',
      '#value' => t('Remove one'),
      '#submit' => array(
        'ajax_example_add_more_remove_one',
      ),
      '#ajax' => array(
        'callback' => 'ajax_example_add_more_callback',
        'wrapper' => 'names-fieldset-wrapper',
      ),
    );
  }
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Submit'),
  );

  // 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.
  // For demonstration only! You don't need this.
  if ($no_js_use) {

    // Remove the #ajax from the above, so ajax.js won't be loaded.
    if (!empty($form['names_fieldset']['remove_name']['#ajax'])) {
      unset($form['names_fieldset']['remove_name']['#ajax']);
    }
    unset($form['names_fieldset']['add_name']['#ajax']);
  }
  return $form;
}

/**
 * Callback for both ajax-enabled buttons.
 *
 * Selects and returns the fieldset with the names in it.
 */
function ajax_example_add_more_callback($form, $form_state) {
  return $form['names_fieldset'];
}

/**
 * Submit handler for the "add-one-more" button.
 *
 * Increments the max counter and causes a rebuild.
 */
function ajax_example_add_more_add_one($form, &$form_state) {
  $form_state['num_names']++;
  $form_state['rebuild'] = TRUE;
}

/**
 * Submit handler for the "remove one" button.
 *
 * Decrements the max counter and causes a form rebuild.
 */
function ajax_example_add_more_remove_one($form, &$form_state) {
  if ($form_state['num_names'] > 1) {
    $form_state['num_names']--;
  }
  $form_state['rebuild'] = TRUE;
}

/**
 * Final submit handler.
 *
 * Reports what values were finally set.
 */
function ajax_example_add_more_submit($form, &$form_state) {
  $output = t('These people are coming to the picnic: @names', array(
    '@names' => implode(', ', $form_state['values']['names_fieldset']['name']),
  ));
  drupal_set_message($output);
}

/**
 * @} End of "defgroup ajax_degradation_example".
 */