Discovering Dojo for Domino: Part 3 - Dijits for Domino

The next thrilling episode in my dojo adventures ...

Firstly, some references: the three primary references I used are The Book of Dojo - Part 2 which gives you an overview of dijits and how they work in general, the Dojo Campus - Feature Explorer which has examples and shows the related code, the dojo API Reference. I also found the following part of the dojo campus through Google: http://docs.dojocampus.org. I can't find a link to it on the main DojoCampus page, but it's very useful.

To create digits, you can add to your http markup, or you can create components programmatically.

Example through markup (from Dojo Campus):

<input id="q01" type="text" name="firstname"
  value="testing testing"
  style="width: 100px;"
  dojoType="dijit.form.TextBox"
  uppercase="true" />

For now, I'm going to leave programatic creation alone. While this would create the visual elements, I'm not sure they would be saved to disk if you are submitting a standard form to your server (rather than POSTing it to an agent). I haven't investigated though and this may be a valid alternative in some circumstances.

The API reference lists all the methods and parameters. Methods include standard event handlers (onClick, onChange, etc), and there are a whole lot of parameters, but some of the most useful are things like: class, style, uppercase and trim. For example, setting trim=true will have the text box automatically remove leading and trailing white space - no extra coding required.

As with the core, you simply need to reference the dojo script libraries in your form's HTML Head Content (see my previous post. You also need to 'dojo.require' the appropriate libraries for the widgets in your JS Header (see Part 1).

For widgets, the only extra part is the style sheets. There are three common themes, the most common of which is the Tundra theme. These come already installed with 8.5, and are located in [program folder]\Domino\data\domino\js\dojo-1.1.0\dijit\themes.

You need to reference the themes in your HTML Head Content along with the script libraries, so my 8.5 test form now contains:

"<link rel="stylesheet" type="text/css" 
  href="/domjs/dojo-1.1.0/dijit/themes/tundra/tundra.css" />" + 
"<script type="text/javascript" 
  src="/domjs/dojo-1.1.0/dojo/dojo.js" 
  djConfig="parseOnLoad:true, isDebug:true"></script>" 

The doc.dojocampus.org site also recommends:

It is recommended you include the theme CSS file before dojo.js to avoid any potential latency issues.

If you use the Tundra theme, you also need to include the class in you form's HTML Body Attributes

"class='tundra' "

First, I created a simple text field. You can add the additional dojo code to either the field properties box (HTML Tab - Other) or the HTML Attributes of the field in the design pane. Both work. The properties box is very small and in general the design pane is easier to work with. The only advantage of the properties box is you don't have to change code if you paste it in there, whereas with the design pane you need to enter a formula which returns a text string. This means you may need to escape double quotes with a backslash, or change double quotes to single quotes.

For the text field, I added the following to the design pane:

"dojoType='dijit.form.TextBox' uppercase='true' trim='true' "

I added the appropriate 'require' statement to the JS Header of the form and I now have a working dijit which automatically converts the text to upper case on exiting the field and trims white space from both ends (and is styed quite nicely too).

Other basic dijits I've tested (check out the Dojo Campus - Feature Explorer for the relevent require function and html attributes):

• Date picker - just a text field, but can be trimmed or a constraint applied
• Time picker - I'm not sure I like this widget much, but again you can apply constraints to define the format
• Number Spinner - Allows user to either type a number or click Up/Down to adjust. Max, Min and number of decimal places can be define.
• Combobox - like a standard html combo box but users can enter values not in list. I had problems with this - see below.
• Filtering Select - like a standard combo box but uses 'Google Suggests' style interface. Again this doesn't work 'out of the box' with Domino, unlike most other widgets

Filtering Select & Combo box

Neither of these work properly with Domino. The reason is that Domino (prior to version 8.5) does not generate valid HTML for a <Select> element - it does not close the <Option> tag with </Option>.

The Combobox will work in IE, but not Firefox. I'm not sure about other browsers. The Filtering Select will work in IE if you add an alias to your picklist (so that Domino generates a value property for the <Option> tag. I am working with IE on an intranet for my current project, so I don't need to worry about the other browsers for now. For filtering selects that don't need an alias I have modified the formula to be something like:

list:="":@DbColumn(....)
list + "|" + list

That way I get the alias, IE is happy and the dijit works, and I get the label returned in my field. If you need to (and are braver than me), you can apparantly modify the dojo files to handle the bad HTML. The Dojomino blog explains how. This is a good reference site, but currently a bit out of date. They have announced that they are releasing an update but it hasn't been posted yet.

All of the dijits include the ability to validate the field. Field prompts are styled as a small tool-tip to the right of the field, error messages are displayed as the user leaves the field, and dijits such as the date and time text boxes handle all the heavy lifting around validating the content. However this is UI level validation only, and does not prevent the form from being submitted with incorrect values.

My next challenges:

1. Modifying the options of combo box 2 when the user makes a selection from combo box 1 and
2. Form level validation

Stay tuned ..