Wim Leers Freelance Drupal Developer

In my session at DrupalCon DC, I promised an initial version of the Episodes module by March 15, which is today. I'm glad to be able to announce that I somewhat met that goal.

If you don't know what it is exactly, I encourage you to read the project description first.

Status

It's not yet completely finished: the basic reporting UI must still be written. But you can already look at the results of each individual page through the Firebug add-on (which I didn't write, it's already available). See the first screenshot for that. That's of course much less useful, but it gives you a clear indication of the potential.
However, before I do that, I first have to work on making other deadlines for other courses.
So what's done already? Here's an overview:

AHAH-powered forms were virtually impossible in Drupal 5 (see the note though). In Drupal 6, this is much easier, thanks to the #ahah property. However, it still is really painful to actually use it.

The flaw

You have to write a menu callback for each AHAH-enabled form item of your form. You have to repeat small variations of this piece of code for each callback:

// Build our new form element.
$form_element = _mymodule_add_something_to_form();
 
// Build the new form.
$form_state = array('submitted' => FALSE);
$form_build_id = $_POST['form_build_id'];
// Add the new element to the stored form. Without adding the element
// to the form, Drupal is not aware of this new elements existence and
// will not process it. We retreive the cached form, add the element,
// and resave.
$form = form_get_cache($form_build_id, $form_state);
$form['somewhere']['very']['deep'] = $form_element;
form_set_cache($form_build_id, $form, $form_state);
$form += array(
  '#post' => $_POST,
  '#programmed' => FALSE,
);
 
// Rebuild the form.
$form = form_builder('mymodule_someform', $form, $form_state);
 
// Render the new output.
$subform = $form['somewhere']['choice'];
$output = theme('status_messages') . drupal_render($subform);
 
drupal_json(array('status' => TRUE, 'data' => $output));

Ok, it does make sense. But it takes some time to get used to – too much – and is a treshold that's big enough for many developers to just not implement AHAH forms. It simply shouldn't be this hard.
This current approach of AHAH forms in Drupal is time consuming, hard to maintain and hard to write tests for.

API

The API of the previous version of HS was a beast. Well, not the API, but the implementations. This has been fixed in version 2 of HS: it's now much more elegant and much easier. If you don't have to alter any forms, you can easily implement all hooks in less than a hundred lines, probably even less. The content_taxonomy implementation for example, is about 75 lines if you don't count the form altering. That should make HS much more attractive to other Drupal developers.

Support Hierarchical Select Dynamically

One of the low-hanging fruits is to support HS dynamically (i.e. use hierarchical select form items when HS is installed, use normal selects otherwise).

What is Hierarchical Select?

For those who don't know Hierarchical Select yet, or HS in short, this is a module that provides a new form element. If you're new to Drupal, you may just have frowned upon reading that. A 'form element' in Drupal's Forms API is something like a button, select or textarea element in HTML, or a GUI widget in a GUI.

Now, the goal of HS is actually very narrow: making selections in hierarchies (hence its name) really simple: improve usability. The prime example and candidate for this is of course Drupal's Taxonomy module. The idea is to first select an item from the root level, then pick one of its children (if it has any), then one of the children of the selected child (if it has any), and so on.

Almost 3 weeks two months ago now, I have released the Hierarchical Select module. (This post was originally written during the DrupalCon, but time has been sparse since then and bugs were there, which is why I'm posting this so late.) It defines a new form element: hierarchical_select. It makes the selection of something in a hierarchy much more usable. By default, selects of the taxonomy module (on node forms) are forced to use hierarchical selects - if the vocabulary is hierarchical. The same is applied to content_taxonomy CCK fields, when the select widget is used.
Note that the hierarchical select form element does not support the selection of multiple items. And obviously, it only selects the "deepest" item.
I'll immediately skip to the demo, because a live demo says so much more than words.

And it has an API!

This part is only interesting to people who want to make use of this form element for other modules than taxonomy.

The module comes with an API, so that any module that manages some sort of hierarchy, can define a rendering function that will be used to render the hierarchical selects. It can't be done completely automagically, because it varies greatly from case to case what input data is necessary to generate the necessary tree structure.
For example: taxonomy needs a vocabulary id and the id of the currently selected term (term id). Another module may only require one id, while another may require 3 ids. You will always get the id of the newly selected item in any of the selects back (which is the term id in the case of taxonomy).

hook_hierarchical_select_render($hsid, $selection, $params)

• $hsid - hierarchical select id, will just be used as a unique identifier in the HTML
• $selection - the value of the item that was selected by the user
• $params - an array of parameters that are passed around, these are considered "static", e.g. the vocabulary id

You can look at modules/taxonomy.inc for an example implementation. See API.txt for details.

Future: Drupal 6 and CCK 2

There's room for improvements in the API. But that'll be for a second version, which will be Drupal 6 only, because of the interesting change in CCK 2: CCK widgets will simply be FAPI form elements. That means that we'll be able to use the hierarchical select form element for several CCK fields!