ATTENTION MODULE DEVELOPERS: I really need additional maintainers to help with this project. If you are interested, please let me know. If you wish to contribute to this project, you can fork it here on Github and issue a pull request. Thank You.

About

Ajax.module can be found at http://drupal.org/project/ajax.

Usage

At the Drupal module admin page, enable the "Ajax" module and the "Ajax ui" module. Also enable any other Ajax plugins that you may need to use.

Go to the Permissions admin screen at "admin/user/permissions" and enable the appropriate permissions for "Ajax ui module".

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 specify other options which are provided by Ajax plugins.

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-instantaneously.

Developers: PHP API

The API documentation applies primarily to 6.x-1.x-dev, and is subject to change.

The Ajax UI 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. A form can be activated with AJAX functionality by specifying the '#ajax' property of the form...

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

Any other properties specified in the $form['#ajax'] array will be sent in the form JSON response in the "options" object.

Ajax.module will in MOST cases automatically detect which form submit buttons should be used for Ajax handling. If, however, you have custom submit buttons which are not being detected for Ajax handling, you can set the '#ajax' property on the submit button. For example...

$form['my_submit'] = array(
  '#type' => 'submit',
  '#ajax' => array(
    'submitter' => TRUE
  ),
  '#value' => t('My Own Submit Button')
);

Ajax.module also 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_alter (&$form, &$form_state, $form_id)

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

The Ajax UI module provides the following hooks...

hook_ajax_types (&$types)

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

hook_ajax_options (&$options)

• $options Assoc
  A list of admin options which can apply to each form.

For more developer information and usage examples, please see the Ajax plugins which are provided in the "ajax/plugins" directory.

Developers: JavaScript API

The Ajax.module JavaScript API provides the following plugin callbacks(s):

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

Where FOO is the name of your plugin.

• hook String
  Name of the action taking place.
• args Assoc/Object
  A keyed object/associative-array of args which are specific to this hook.

hook is the current action taking place. The following hooks are available in chronological order:

• init
  On page load.
• submit
  Before form is submitted.
• redirect
  If function returns true, page will be redirected. If function returns false, no redirection will occur.
• message
  This hook is called when a message is to be displayed on the current webpage after a submission is complete. If this function returns false, the default message will not be displayed. Otherwise, the default message will display.
• afterMessage
  After all messages are displayed.
• scrollFind
  Provided by the ajax_scroller module. This is called so that external plugins can specify a element to stop scrolling at.
• complete
  Called after successful form submission. (need more info here)

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

Other considerations

For anyone trying to nest a form inside of something else and have the page stay the same and the form submit correctly, do the following:

1) create a new module - or if you have a generic one you use for site-specific changes, use that. You need a .module file and a .info file
2) create a function called YOUR_MODULE_NAME_form_THE_FORM_YOU_ARE_TESTING_alter (this is an implementation of the hook_form_FORM_ID_alter) similar to this:

function node_bulk_create_form_page_node_form_alter (&$form, &$form_state) {
  if (arg(2) != 'edit') {
    $form['#action'] = url('node/add/page');
  }
}

3) Don't forget to use the "Ajax plugin - disable_redirect" module, which adds a "disable redirect next to each form you AJAXify, so that you are not redirected on form submission.
Note that my module name above is 'node_bulk_create' and the form I'm altering is 'page_node_form'.

That's it. Note that the above only works on node creation (add) forms since that's all I'm embedding in my case. I'm not embedding the edit form. But you could. Clearly, the #action is what matters here.

FYI, I placed the call to the node form in a block, then put the block inside of a 'quicktab' displayed via 'contemplate' on another kind of content type's view page. Works great.

Notes

• This module will work with forms displayed in a Thickbox if you enable the provided Thickbox plugin. However, it will only work 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.
• If you are using the Image FUpload module, be careful not to enable the "image" content type in the Ajax UI admin screen.
• This module will work with the Audio module, although the Audio module may issue PHP warnings after uploading audio content.
• This module will work with the FCKEditor module, however it has only been tested with fckeditor-6.x-1.x-dev. Other versions may not work as expected.