CiviCRM.HierSelect Widget

There are many screens in CiviCRM where the options in one drop-down affect what you see in a second or third drop-down menu. For example, when you do an Import or Export, and select Email - you then get a second drop-down to select a location (Home, Work, etc.). The widget which we use for this is PEAR's Hierarchical Select. We have been looking for an Ajax-based replacement for this - and built one to manage Country -> State/Province selection in 1.8. However, we needed a solution that we could use for all cases and that could handle 2 OR 3 related drop-downs. Ajax solution should make screens load more quickly since we're not loading ALL the possible option / combinations at once. Being a beginner and wanting to learn and experiment with dojo, i thought of doing it as a side mini-project. On the way, i got stuck many times, with no hopes of ever completing it or moving forward. But clues from online searches and dojo documentation, kept pushing me forward. And i am happy to announce that the ajax hierselect widget is now ready with decent set of features, And implementing it across the codebase (v2.1) is one of the agenda in NZ Meetup. This is how we would include the widget in civicrm (templates) : <div name="hs_widget" dojoType="civicrm.HierSelect" url1="jsonURL1" url2="jsonURL2"></div>

 

Features

• Choose between 2 to 3 selectors The widget provides flexibility of including upto 3 selectors, by adding an "url3" attribute, like: <div name="hs_widget" dojoType="civicrm.HierSelect" url1="jsonURL1" url2="jsonURL2" url3="jsonURL3"></div>
• Onload defaults Setting "default" attribute, makes selector select an option, when page loads. For example: <div name="hs_widget" dojoType="civicrm.HierSelect" url1="jsonURL1" url2="jsonURL2" url3="jsonURL3" default1="value1" default2="value2" default3="value3"></div>
• Place each of the selectors anywhere you like You might want to place the selector2 and selector3 somewhere different from that of selector1. This widget looks for "id_widgetName_(selectorNumber-1)" on the page and if found, positions the selector there, otherwise puts all the selectors together. For above shown example it would be 'id_hs_widget_1' OR 'id_hs_widget_2'. Say you want to place selector1 in the first row, while selector2 on third row of a table: <table> <tr><td>some label (selector1)</td><td><div name="hs_widget" dojoType="civicrm.HierSelect" url1="jsonURL1" url2="jsonURL2"></div></td></tr> <tr><td>some label ( row - 2 )</td><td>some description..</td></tr> <tr><td>some label (selector2)</td><td><span class="tundra"> <span id="id_hs_widget_1"></span></span></td></tr> </table> Class is required to apply the theme, without which selector would not be rendered properly (Though looks easy, it took me hell lot of time to figure this out :)). Note: This widget uses 'tundra' theme and no experiment has been done as of yet, with other themes.
• First in list OR None When selected an option from first selector, choose if a) Second/third selector should load first option from their own list OR b) Second/third selector should NOT display anything, but display any message/option - if available with value ''. Option 'b' is the default behaviour for the widget. To switch to first option, "firstInList" attribute should be set to true: <div name="hs_widget" dojoType="civicrm.HierSelect" url1="jsonURL1" url2="jsonURL2" firstInList="true"></div>

The code can be obtained from here. Extending this widget for N selectors, can be another interesting project which certainly would not be as simple as it sounds ;).

Comments

For Drupal, you could have chosen to use my Hierarchical Select module. But I guess that's not portable enough, because CiviCRM supports more than just Drupal.

Anyway, it's nice to see that although I had not even heard about PEAR's Hierarchical Select, I've developed something similar (but with much more features) and gave it the exact same name! :)