##
## AJAX Forms README
##

  Author: Brendon Crawford
  Date: 2009-01-11
  Homepage: http://drupal.org/project/ajax
  IRC: irc://freenode.net/#drupy

##
## ABOUT
##

  The AJAX Forms module will "AJAXify" any Drupal form. This essentially allow
  for validation, preview, and submission without a page refresh.

  AJAX Forms supports most forms out of the box. For more complex forms a
  plugin/API system is provided to allow easy AJAX Forms integration.

  By default in Drupal, when a form is submitted, the values of that form are
  sent through a series of Drupal validation procedures. When these validations
  are completed the validation messages are normally sent back to the user with
  a standard page refresh.

  For example, if a user fills out a form which requires a first name, but the
  user leaves these fields blank, they will be presented with a message that
  says "First Name is Required".

  This module allows the validation messages to be sent back to the user without
  a page refresh, so they appear in realtime. This makes for a more streamlined
  user experience. If the submitted form has no errors, the page will be
  redirected to the appropriate submission landing page.

##
## USAGE
##

  At the Drupal module admin page, enable the "Ajax forms" module. Also enable
  any other Ajax forms plugins that you may need to use.
  
  Next, go to "admin/settings/ajax" and select the forms for which you want to
  use AJAX handling from the "Default Forms" section. You can also optionally
  specify a form ID in the "Custom Forms" section.

  To test the module, go to one of the forms which you selected or specified.
  For example if you selected "Content Type: Blog", then go to "node/add/blog".
  Then, fill out the form, intentionally inputting invalid data or leave a
  required field blank. Submit the form. You should then see the validation
  messages appear at the top of the form near-instantaniously.

##
## DEVELOPERS: PHP API
##

  The AJAX Forms module will properly handle MOST forms out of the box. If,
  however, your forms require special or complex handling, a plugin/API system
  has been provided to allow for easy integration. AJAX Forms provides the
  following module hooks:

    hook_ajax_validate_fail (&$form, &$form_state, &$data)
    
      $form Assoc
        A Drupal form object
      $form_state Assoc
        A Drupal form_state object
      $data Assoc
        The AJAX Forms internal data object.

    hook_ajax_validate_pass (&$form, &$form_state, &$data, &$pass)

      $form Assoc
        A Drupal form object
      $form_state Assoc
        A Drupal form_state object
      $data Assoc
        The AJAX Forms internal data object.
      $pass Bool
        Determines whether or not data should move to submission stage

    hook_ajax_types (&$types)

      $types Assoc
        A list of available forms that an end user
        can select for AJAX Forms to use.

    hook_ajax_alter (&$form, &$form_id)

      $form Assoc
        A Drupal form object
      $form_id String
        A Drupal form ID

  A module can also specify that a form should ALWAYS use AJAX Forms
  regardless of user selection, by setting the "#ajax" property of the form
  to TRUE. Example:

    foobar_form_alter(&$form, $form_state, $form_id) {
      $form['#ajax'] = TRUE;
    }

  For more developer information, please see the example AJAX Forms plugins
  which are provided in the "ajax/plugins" directory.

##
## Developers: JavaScript API
##

  The Ajax Forms JavaScript plugin provides the following plugin callbacks(s):

    Drupal.Ajax.plugins.FOO(hook, args)

  Where FOO is the name of your plugin.

    hook String
      A Drupal form object
    args Assoc/Object
      A keyed object/associative-array of args which are specific to this hook.

  hook can be one of:

    scrollFind
      Executes as window scrolls up after Ajax response.
    init
      On page load.

  For Ajax Forms plugins usage examples, please see the "thickbox" and
  "tinymce" plugins which are provided with the Ajax Forms module in the
  "ajax/plugins" directory.

##
## NOTES
##

  This module will work out of the box with forms displayed in a Thickbox.
  However, it will only work out of the box with the "AJAX Content" Thickbox,
  NOT the "iFramed Content" Thickbox.

  This module will work with the Captcha module (6.x-1.0-rc2) using the
  provided Captcha Plugin, but you must first apply a set of patches to the
  captcha module which are provided in the "ajax/plugins/captcha/patches"
  directory.