ajax_process_form

Versions

mediamosa-21

ajax_process_form($element, &$form_state)

Add AJAX information about a form element to the page to communicate with JavaScript.

If #ajax['path'] is set on an element, this additional JavaScript is added to the page header to attach the AJAX behaviors. See ajax.js for more information.

Parameters

$element An associative array containing the properties of the element. Properties used:

• #ajax['event']
• #ajax['path']
• #ajax['wrapper']
• #ajax['parameters']
• #ajax['effect']

Return value

None. Additional code is added to the header of the page using drupal_add_js().

Related topics

AJAX framework

Drupal's AJAX framework is used to dynamically update parts of a page's HTML based on data from the server. Upon a specified event, such as a button click, a callback function is triggered which performs server-side logic and may return...

Code

includes/ajax.inc, line 449

<?php
function ajax_process_form($element, &$form_state) {
  $js_added = &drupal_static(__FUNCTION__, array());

  // Nothing to do if there is neither a callback nor a path.
  if (!(isset($element['#ajax']['callback']) || isset($element['#ajax']['path']))) {
    return $element;
  }

  // Add a reasonable default event handler if none was specified.
  if (isset($element['#ajax']) && !isset($element['#ajax']['event'])) {
    switch ($element['#type']) {
      case 'submit':
      case 'button':
      case 'image_button':
        // Use the mousedown instead of the click event because form
        // submission via pressing the enter key triggers a click event on
        // submit inputs, inappropriately triggering AJAX behaviors.
        $element['#ajax']['event'] = 'mousedown';
        // Attach an additional event handler so that AJAX behaviors
        // can be triggered still via keyboard input.
        $element['#ajax']['keypress'] = TRUE;
        break;

      case 'password':
      case 'textfield':
      case 'textarea':
        $element['#ajax']['event'] = 'blur';
        break;

      case 'radio':
      case 'checkbox':
      case 'select':
        $element['#ajax']['event'] = 'change';
        break;

      default:
        return $element;
    }
  }

  // Adding the same JavaScript settings twice will cause a recursion error,
  // we avoid the problem by checking if the JavaScript has already been added.
  if (!isset($js_added[$element['#id']]) && isset($element['#ajax']['event'])) {
    $element['#attached']['library'][] = array('system', 'form');
    $element['#attached']['js']['misc/ajax.js'] = array('weight' => JS_LIBRARY + 2);

    $settings = $element['#ajax'];

    // Assign default settings.
    $settings += array(
      'selector' => '#' . $element['#id'],
      'effect' => 'none',
      'speed' => 'none',
      'method' => 'replace',
      'progress' => array('type' => 'throbber'),
      'formPath' => implode('/', $element['#array_parents']),
    );

    // Process special settings.
    $settings['url'] = isset($settings['path']) ? url($settings['path']) : url('system/ajax');
    unset($settings['path']);
    $settings['button'] = isset($element['#executes_submit_callback']) ? array($element['#name'] => $element['#value']) : FALSE;

    // Convert a simple #ajax['progress'] string into an array.
    if (is_string($settings['progress'])) {
      $settings['progress'] = array('type' => $settings['progress']);
    }
    // Change progress path to a full URL.
    if (isset($settings['progress']['path'])) {
      $settings['progress']['url'] = url($settings['progress']['path']);
      unset($settings['progress']['path']);
    }
    // Add progress.js if we're doing a bar display.
    if ($settings['progress']['type'] == 'bar') {
      $element['#attached']['js']['misc/progress.js'] = array('cache' => FALSE);
    }

    // @todo This is incompatible with drupal_render() caching, but cannot be
    //   assigned to #attached, because AJAX callbacks render the form in a way
    //   so that #attached settings are not taken over.
    drupal_add_js(array('ajax' => array($element['#id'] => $settings)), 'setting');

    $js_added[$element['#id']] = TRUE;
    $form_state['cache'] = TRUE;
  }
  return $element;
}
?>