modules/ahah_helper/README.txt

$Id: README.txt,v 1.1 2008/08/29 18:58:21 wimleers Exp $

Description
-----------
Drupal 6's Forms API is great, but its AHAH support (a technique similar to
AJAX) is lacking. You have to write a menu callback for every AHAH-enabled
form item of your form. This is time consuming, hard to maintain and hard to
write tests for. Not to mention that the code for those menu callbacks is not
easy to understand, yet always the same. ("What's that piece of code for?" –
"I'm not sure, it's just necessary…") See my blog post about this if you want
more details: http://wimleers.com/blog/ahah-helper-module.

This module simplifies that. It allows you to:
1) not write any menu callback at all.
2) still not write any JavaScript at all.
3) have a sole, central form definition function that has some if-tests to
   support a changing form based on the user's input, i.e. by checking
   $form_state['values'] and/or $form_state['storage']. This is in fact the
   exact same system you've been applying if you've already written multi-step
   forms. This makes sense, because AHAH forms are in fact normal multi-step
   forms, that just happen to be updatable through AHAH as well.
   You still have to use the #ahah property and set a wrapper, but you provide
   a "magical path" that will automatically rebuild and render the desired
   part of the form. If the part of the form that you want to be rendered is
   $form['fapi']['rocks'] then you would do
   'path' => ahah_helper_path(array('fapi', 'rocks')) and that's it.
   Adding graceful degradation just became really easy: just create buttons
   with the appropriate text, set '#submit' => array('ahah_helper_submit'),
   and off you go. You'd probably create such a button for every AHAH-powered
   form item. The exact same code will be used as when JavaScript would be
   enabled. (If you've got a AHAH-powered select called 'Usage', you'd
   probably name the button 'Update usage'. You get the point.)
   And thanks to these buttons, writing functional tests now becomes trivial
   as well. Because the same code is used when JavaScript is disabled (through
   the buttons) or enabled (through AHAH callbacks), just press the buttons in
   your tests and you'll be fine!
4) skip form validation for all AHAH updates that do not call validate or
   submit callbacks.
5) have new AHAH-powered form items added in an AHAH callback (previously not
   supported).

Look at the included ahah_helper_demo module for an example.


Dependencies
------------
None.


Installation
------------
1) Place this module directory in your modules folder (this will usually be
"sites/all/modules/").

2) Enable the module.


Sponsors
--------
Dries Buytaert & Benjamin Schrauwen of http://mollom.com.


Author
------
Wim Leers

* mail: work@wimleers.com
* website: http://wimleers.com/work

The author can be contacted for paid customizations of this module as well as
Drupal consulting and development.
1	$Id: README.txt,v 1.1 2008/08/29 18:58:21 wimleers Exp $
2
3	Description
4	-----------
5	Drupal 6's Forms API is great, but its AHAH support (a technique similar to
6	AJAX) is lacking. You have to write a menu callback for every AHAH-enabled
7	form item of your form. This is time consuming, hard to maintain and hard to
8	write tests for. Not to mention that the code for those menu callbacks is not
9	easy to understand, yet always the same. ("What's that piece of code for?" –
10	"I'm not sure, it's just necessary…") See my blog post about this if you want
11	more details: http://wimleers.com/blog/ahah-helper-module.
12
13	This module simplifies that. It allows you to:
14	1) not write any menu callback at all.
15	2) still not write any JavaScript at all.
16	3) have a sole, central form definition function that has some if-tests to
17	support a changing form based on the user's input, i.e. by checking
18	$form_state['values'] and/or $form_state['storage']. This is in fact the
19	exact same system you've been applying if you've already written multi-step
20	forms. This makes sense, because AHAH forms are in fact normal multi-step
21	forms, that just happen to be updatable through AHAH as well.
22	You still have to use the #ahah property and set a wrapper, but you provide
23	a "magical path" that will automatically rebuild and render the desired
24	part of the form. If the part of the form that you want to be rendered is
25	$form['fapi']['rocks'] then you would do
26	'path' => ahah_helper_path(array('fapi', 'rocks')) and that's it.
27	Adding graceful degradation just became really easy: just create buttons
28	with the appropriate text, set '#submit' => array('ahah_helper_submit'),
29	and off you go. You'd probably create such a button for every AHAH-powered
30	form item. The exact same code will be used as when JavaScript would be
31	enabled. (If you've got a AHAH-powered select called 'Usage', you'd
32	probably name the button 'Update usage'. You get the point.)
33	And thanks to these buttons, writing functional tests now becomes trivial
34	as well. Because the same code is used when JavaScript is disabled (through
35	the buttons) or enabled (through AHAH callbacks), just press the buttons in
36	your tests and you'll be fine!
37	4) skip form validation for all AHAH updates that do not call validate or
38	submit callbacks.
39	5) have new AHAH-powered form items added in an AHAH callback (previously not
40	supported).
41
42	Look at the included ahah_helper_demo module for an example.
43
44
45	Dependencies
46	------------
47	None.
48
49
50	Installation
51	------------
52	1) Place this module directory in your modules folder (this will usually be
53	"sites/all/modules/").
54
55	2) Enable the module.
56
57
58	Sponsors
59	--------
60	Dries Buytaert & Benjamin Schrauwen of http://mollom.com.
61
62
63	Author
64	------
65	Wim Leers
66
67	* mail: work@wimleers.com
68	* website: http://wimleers.com/work
69
70	The author can be contacted for paid customizations of this module as well as
71	Drupal consulting and development.