The Dojo Javascript Toolkit - Powerful, but Unfinished

Javascript toolkits are collections of tools that provide easy interfaces to both basic and advanced functionality that allow developers to concentrate on the business functionality of their application.  However, some are more polished than others; I'll tell you about a recent experience with Dojo, an increasingly popular toolkit.

I had written a simple PHP application to graph web server statistics, such as HTTP daemons and MySQL connections.  The application utilized JpGraph to generate graphs from tabular data.   The first page provided documentation and the interface to select the services to graph and the date/time range, and the second parsed and displayed the requested information.  For the date and time picker, I used for loops and an array to generate options for the drop-down lists.  It was ugly, but due to the low volume of use, it was enough.

However, as our organization started having more web server performance related issues, we increasingly relied on the tool, and the kludgy user interface became painfully obvious.  Wouldn't it be easier to select a date on a calendar rather than scrolling through an option list?  Can we have all the information and options available on one page, yet have an uncluttered interface?  While it was just a private utility, it needed improvement.

Enter Dojo 0.4, the modular Open Source Javascript toolkit.  A number of useful Widgets in its arsenal included a date picker, time picker, tool tips, and tabbed content.  It seemed like an ideal tool for overhauling the GUI without spending undue amounts of time tweaking, and I had easily utilized the collapsible TitlePane widget in another application.

However, the lack of good documentation quickly became an issue; a number of features or techniques mentioned in the incomplete API didn't work out of the box.

The date and time picker provided to be the hardest to deal with.  The method of retrieving the selected date and the selected time were different and incorrectly documented (DatePicker), if at all (TimePicker).  In addition, there was no documentation on how to ID the individiual widgets for retrieval.

Google searches for documentation found developer discussion threads such as, "Who broke the time picker?" but providing no working examples that worked with a form submission.  I found an email exchange between a user and a developer about another widget that provided the key on how apply an ID, and a third discussion revealed how to actually retrieve the value so it could be POSTed.

Finally, I turned to the source code.  According to a code comment, the published mechanism for getting the DatePicker value was deprecated, and the function for TimePicker was completely different than the DatePicker.

Armed with the information from a variety of hard-to-find sources, I finally got it to function... after wasting several hours researching, experimenting, and adjusting.  Fortunately, the tool tips and tabbed content were much easier to implement than the date/time pickers.

The end result was highly polished, easy to use and beautiful.  I felt drained by the experience; a released toolkit shouldn't be this hard to use.  Using the beta (or alpha?) release as a justification for bad documentation is not an acceptable excuse; if you want to help others, you need to take the time to make sure they can use it.

Moroha is the Japanese word for "double-edged," and it sums up my experience with Dojo; it's powerful, but careful how you handle it.

Code:

To set up the two widgets, use the following HTML:

<div dojoType="DropDownDatePicker" widgetId="wid_from_date"></div>
<div dojoType="TimePicker" widgetId="wid_from_time"></div>

Somewhere within the form, you'll need a hidden value for POSTing.

<input type="hidden" name="from" value="">

And finally, the submit button. I used the Dojo widget.

<button dojoType="Button" onclick='submitform()'>Submit</button>

The javascript (sans validation):

function submitform(form) {
 var datepicker_from = dojo.widget.byId("wid_from_date");
 var timepicker_from = dojo.widget.byId("wid_from_time");
 document.forms[0].elements["from"].value = datepicker_from.getValue() + " "
  + timepicker_from.selectedTime['hour'] + ":"
  + timepicker_from.selectedTime['minute'] + " "
  + timepicker_from.selectedTime['amPm'];
 document.myform.submit()
}

The result can be parsed with the PHP strtotime function.

$start = strtotime($_POST['from']);