AHAH in Drupal is a feature provided by the Forms API.
- You write the form using the Drupal Forms API.
- You specify what button activates the AHAH behavior.
- You specify what part of the form's HTML is to be replaced by the callback
- You write a callback that generates the replacement HTML
- Drupal manages everything so that when the button or control is used, the callback gets called and the replacement of HTML is done
The AHAH framework is fully integrated into Drupal 6 so all you need to do is hook into it using Drupals form API. Here's an example of how to make the form API to use AHAH.
<?php
$form['my_form_submit'] = array(
'#type' => 'submit',
'#value' => t('Submit'),
'#weight' => 1,
'#submit' => array('my_form_submit'),//none JS version
'#ahah' => array(
'event' => 'click',
'path' => 'mymodule/js',
'wrapper' => 'myform-wrapper',
'method' => 'replace',
'effect' => 'fade',
'progress' => array(
'type' => 'bar',
'message' => t('Loading...')
)
),?>
We're focusing on the #ahah array at the end of the form array, let me explain the various parameters one by one:
#ahah['event']
This is the type of event that must be perform on the $form item (in this example the Submit button) in order for the AHAH behaviour to be triggered.
Possible values: 'click', 'blur', 'change' (Optional will default to click)
Examples: user clicking a button (click) or user selecting a value in a drop down menu (change)
#ahah['path']
This is the menu item or URL that is called when the "event" has been triggered. Without this AHAH will not be triggered.In the above example you would need to have a coresponding menu item defined in your hook_menu like so:
<?phpfunction mymodule_menu() {
$items['mymodule/js'] = array(
'page callback' => 'mymodule_js',
'access arguments' => array('access mymodule js'),
'type' => MENU_CALLBACK,
);
...
return $items;
}
/**
* callback function for mymodule/js
* The return HTML will be outputted by AHAH
*/function mymodule_js() {
return drupal_json(array('status' => TRUE, 'data' => "Hello Drupal World"));;
}?>
It's important the you use the
drupal_json function so that Javascript can understand the returned values/HTML.
Alternatively you could use the
AHAH helper module which can handle all the menu definitions for you.
#ahah['wrapper']
This is the ID of the HTML element on the current page that should be updated with the returned HTML from our #ahah['path'] defined menu path.
In our example
'wrapper' => 'mymodule-wrapper' corresponds to
<div id="mymodule-wrapper">.....</div> and this div would display the "Hello Drupal World" text returned by our mymodule_js() menu function when AHAH has been triggered.
#ahah['method']
This is how you want the HTML returned from our #ahah['path'] menu function to be attached to our #ahah['wrapper'] defined wrapper.
By default it with replace the HTML currently in the wrapper with the new HTML, but you can also have the follow:
'after' = Insert returned HTML after the wrapper element'append' = Append returned HTML to the inside of our wrapper element.
'before' = Insert returned HTML before our wrapper element.
'prepend' = Prepend returned HTML to the inside of our wrapper element.
#ahah['effect']
This is the jQuery effect you want to apply to the wrapper element when it receives the new HTML from our menu function.
Possible values: 'none' (default), 'fade', 'slide'.
#ahah['progress']
This is the type of animation you want to display while the user is waiting for the AHAH menu function to response. It can either be a progress bar or a throbber icon and you can also add an optional message too.The #ahah['progress'] value should be an array of settings (see example above). Here are the full parameters:
#ahah['progress']['type'] = Type of animation to display, bar or throbber
#ahah['progress']['message'] = An optional message that should be displayed with the progress bar or throbber. You should wrap the text in the t().
#ahah['progress']['url'] = An optional URL to a menu item that determines how full the progress bar is.
