Localizing Declaratively Created Dojo Widgets | WebReference

Localizing Declaratively Created Dojo Widgets

By Rob Gravelle


Dojo widgets automatically perform localization tasks such as number/date formatting and the generation of validation messages. There's also a i18n module to help you display your own localized labels, page content, and button values. I explained how to display localized page content in the Dojo i18n: a Pure JavaScript Localization Solution article. In this article, I use the same i18n framework to add multilingual support for Web forms.

It's a little trickier than doing a document.writeln() or setting a <SPAN>'s innerHTML property. For starters, we have the option of setting display text before or after form controls have been "widgetized", that is to say converted into Dojo widgets. There is no clear answer, as both paths will get you there. I use the before widgetizing approach here to localize the investing newsletter subscription form that I created in my Take Your Web Forms to the Next Level with Dojo article. On form submission, I will also validate the form and present a localized dijit.Dialog to the user.

The Form Template

Here is the HTML markup for the form, which includes Dojo-specific properties that will allow Dojo to convert the controls to widgets:

I used a table to present the form fields in a tabular format. While it is considered bad practice to use tables to position page elements, it is acceptable to use them to lay out page contents in a tabular column and row format.

A second reason for using tables is that it avoids clashes with the Dojo CSS theme. This is what the form looks like before the Dojo scripts and CSS have been applied to it:

Making the Before or After Choice

In my Dojo Dijit and Dojox Controls Localization Primer article, I established that a good place to set localized text is in the dojo.addOnLoad() event because it fires after all of the form controls have been loaded. One possible advantage to setting text before widgetizing takes place is that you can leverage your existing knowledge of standard HTML form controls. Another key consideration is that getting some widget properties is not always a straightforward exercise.

To turn off parsing, we have to set the djConfig parseOnLoad attribute to false. In the dojo.addOnLoad() event, we can call the dojo.parser.parse() method directly after we've set all of our display text. Here is the JavaScript code that initializes the djConfig variable, imports the dojo.parser module, and sets up the control localizing to take place in the dojo.addOnLoad() event:

Setting Labels

Labels present an problem because there currently is no replacement Dojo widget for them. Typically, they present themselves as anonymous text nodes, which can be difficult to identify. What we need is a common tag or class that can be utilized to easily group them. One way to do that is to enclose them in <SPAN> tags with a common class name. An even better choice is to use the HTML <LABEL> tag, which specifically defines a label for an input element. It also offers the benefit of binding to its input control via the for attribute. Here is the HTML code for the name textbox and its associated label:

Now we can collect them using the dojo.query() method and iterate over each label using a forEach().

The dojo.query() function is a really great DOM utility that returns a list of nodes based on a CSS3 selector. We can also pass it a root node to start from. Here, we can supply the newsForm form element because all of the labels are included within it. After you've got a collection of DOM nodes, you usually should iteratively process them in some way. The dojo.forEach() function can be applied directly on the DOM nodes collection using dot notation. It will pass the node to whatever function we supply so that we can reference it. The dojo.attr() method is used to obtain a reference to the label's for attribute.

From there, we can set the text using the label node's innerHTML property. Note that the next example assumes that we've already retrieved the localized text, which is stored in the nlsStrings array. See the Dojo Dijit and Dojox Controls Localization Primer article for instructions on how to initialize the localized text. The following code goes at the top of the dojo.addOnLoad() event: