A Dojo widget is a collection of DOM elements created from the HTML tags that describes its structure. The HTML for each widget is contained is a separate file and saved in a special directory. The following example will describe one HTML file and identify its location. The example will explain the general technique that all widgets use to define their structure in HTML.

Let’s start with one of the simplest widgets, a text box. This widget replaces the standard HTML text field. Following is an example of a simple text field that would allow the user to type in an address.

        Address: <input type="text" name="address" />

This field in this example is preceded by a label that describes the field on the web page. Figure 6.2 shows how this field would display on a page (in the absence of additional styling).

Figure 6.2. Standard HTML text box

We’re going to replace this standard HTML widget with the Dojo equivalent, using the declarative method. This means we’ll use HTML markup within the body of the page to define the widget. The alternative is to use the programmatic method that uses JavaScript. The following HTML markup would build the Dojo widget.

    <br><br>(Plain HTML ) Address:
    <input type="text" name="address" />

    <br><br>(Dojo Widget) Address:
    <input type="text" name="address" dojoType="dijit.form.TextBox"/>

I also added some additional HTML to include the regular widget, the Dojo widget, and just a bit of formatting. Figure 6.3 shows how the original HTML text box and the Dojo text box would appear.

Figure 6.3. Dojo text box compared with standard HTML text box

Remember, for the example to work, we’ve got to make sure we’ve included Dojo, started the parser, and included the widget code. We’ll repeat the code for this here, but for more detail, see the tutorial in Part I, “A Dojo Tutorial.”

        <script type="text/javascript"
            src="../dojo-release-1.0.2/dojo/dojo.js"
            djConfig="parseOnLoad: true"></script>

        <script type="text/javascript">
            dojo.require("dijit.form.TextBox");
        </script>

There are some obvious differences between the plain HTML widget and the Dojo widget. For instance, the background color for the Dojo widget is yellow. Why do these differences exist? To answer that question we need to examine the actual DOM elements that have been created. We’ll use the Firebug plug-in for Firefox to see the DOM elements represented as HTML.

      <br/><br/>(Plain HTML ) Address:
        <input type="text" name="address"/>

        <br/><br/>(Dojo Widget) Address:

        <input
            id="dijit_form_TextBox_2"
            class="dijitTextBox"
            type="text"
            autocomplete="off"
            dojoattachevent="onmouseenter:_onMouse,
                onmouseleave:_onMouse,
                onfocus:_onMouse,
                onblur:_onMouse,
                onkeyup,onkeypress:_onKeyPress"
            name="address"
            dojoattachpoint="textbox,focusNode"
            tabindex="0"
            widgetid="dijit_form_TextBox_2"
            value=""
            aaa:valuenow=""
            aaa:disabled="false"
            style=""/>

Firebug looks at the DOM after it is modified by the JavaScript on the web page and converts the DOM back to the equivalent HTML. You might expect that the HTML displayed from Firebug should be the same as the HTML we created in the original source for the page. And in the case of the HTML for the plain text widget, it is. However, the Dojo parser looks for Dojo widgets defined in HTML and replaces them with additional DOM elements and attributes. That is why the HTML we see from Firebug for the Dojo widget seems so much different from the HTML we typed into the source page.

Why are the differences there? The obvious answer is that Dojo put them there. But how? Dojo does it by replacing the entered HTML with alternate HTML, which it calls a template. The template contains most of the replacement HTML with a few hooks where Dojo can add some additional information.

Let’s review the HTML template for this widget. First we have to find it. The HTML markup containing the structure of a widget (its template) can be found by looking for its “template” directory in the path corresponding to its package name. Our widget is in the package “dijit.form,” so we should look for the template subdirectory at “dijit/form/template” as shown in Figure 6.4. The figure shows only the relevant directories and files, and your directory structure may be slightly different depending on the version of Dojo you are using.

Figure 6.4. Location of templates directory in dijit.form package

Below is the code in the “TextBox.html” file. It’s been reformatted by adding some line breaks to make it more readable. Otherwise, the code shown is exactly as what is in the file.

         <input
             class="dojoTextBox"
             dojoAttachPoint='textbox,focusNode'
             name="${name}"
             dojoAttachEvent='
                 onmouseenter:_onMouse,
                 onmouseleave:_onMouse,
                 onfocus:_onMouse,
                 onblur:_onMouse,
                 onkeyup,onkeypress:_onKeyPress'
             autocomplete="off"
             type="${type}"
         />

Now we can see why the HTML from Firebug looks different than what we entered in the source file. It has simply been replaced by the preceding template file. However, there are a few differences—a few places where Dojo has changed the value in the template. The first difference is in the following line from the template file.

         name="${name}"

Compare this to the same line from Firebug:

         name="address"

How did “${name}” from the template get replaced with “address” in the final HTML? This was done by the Dojo parser, which looks for values in the template and replaces them with attributes from the actual HTML. The “$” character is a special symbol used to name a variable in the template file that will be replaced with an attribute value from the HTML markup with the same name. In other words, the name attribute from the HTML markup in the source was used. Remember, the name attribute was in the original HTML as shown as follows in bold.

    <br><br>(Plain HTML ) Address:
    <input type="text" name="address" />

    <br><br>(Dojo Widget) Address:
    <input type="text" name="address" dojoType="dijit.form.TextBox"/>

This value replacement is a general purpose process that can be used to substitute any attribute value into the template. It is a way of passing data from the HTML markup to the template. The same mechanism is used to pass type="text" into the template as well for the assignment of the type="${type}" line.

The id and widgetid attributes in the template are created automatically by Dojo. They can be assigned by setting the value of these attributes in the markup. In this case, Dojo made up some values based on a simple naming scheme.

There are also some new attributes that don’t seem to come from the template. These are autocomplete, tabindex, and value. They have also been added automatically by Dojo for this widget type. Different widget types also have some unique properties added. We explore these in later chapters when we examine individual widgets.

We now have a much better idea how Dojo is updating the DOM for this widget. However, there are still some open issues. For example, why does the text area for the Dojo widget appear longer and with a slightly different border? We need to examine how Dojo applies styles to widgets.

You may have noticed that the Dojo TextBox widget does not look the same as the standard HTML text box. This is because Dojo has applied some special styling to the widget. One of the three primary elements of every Dojo widget is the set of styles associated with it. How does the style get applied? We can answer that by examining one of the attributes in the DOM element for the widget we’ve been discussing. The following code comes from the HTML defined in the template file for the TextBox Dojo widget.

       class="dojoTextBox"

The class attribute is used to associate various styles to the DOM element. The specific styles are unique to each widget. The TextBox widget uses only a single style, but many Dojo widgets use multiple styles. The various Dojo widget styles are defined in CSS files, which can be found in the Dojo directory structure.

Inside the subdirectory “dijit/themes” we can find the file “dijit.css.” This file contains the styles for most of the Dojo widgets. Additionally, Dojo also provides a number of alternative themes that can be used to apply additional styling beyond the default.

Figure 6.5 shows a screen shot of the directory structure used to hold the various style sheets including images used by the styles.

Figure 6.5. Location of Dojo widget styles files

We’ll look inside the “dijit.css” file and see if we can find the style information related to this widget. With just a bit of searching, we can find the following style definitions.

         .dijitTextBox,
         .dijitComboBox,
         .dijitSpinner {
                 border: solid black 1px;
                 width: 15em;
         }

This code assigns a solid black border to any DOM element whose class is either dijitTextBox, dijitComboBox, or dijitSpinner. It also assigns these elements a default width of 15em. The “em” is a unit of measure roughly equivalent to a character at the current font size.^[2]

You can customize the style of a Dojo widget by adding properties to the appropriate style. For instance, if we wanted the background color of all TextBox widgets to be yellow, we could simply add the background property to the dijitTextBox style.

          <style>
          .dijitTextBox {
                  background: yellow;
          }
          </style>

Of course, you’ll probably want to include this in a separate CSS file so that you can use it from all your pages. This would allow you to create your own style on top of the Dojo default style. Dojo has done some of this work for us already. They’ve provided an additional style called Tundra that you can use as a base or as a model for your own themes.

We’re heading toward a complete understanding of Dojo widgets. Are we there yet? Not quite. There is one more element we need to review to complete our understanding of Dojo widgets. Now we’ll look at the JavaScript code associated with each widget we create.

A widget is a control that possesses behavior. But where does all that behavior reside? The functionality of a widget is provided by a JavaScript object associated with the widget that contains properties and methods not contained in the DOM element.

The JavaScript object is created from a constructor function defined for each widget. In the example we’ve been following for dijit.form.TextBox, we can find that constructor function in a file within the “dijit/form” subdirectory. Notice how the widget package name corresponds to a subdirectory in the Dojo directory structure. Figure 6.6 is a screenshot of the directory structure for TextBox showing only the files relevant for our example.

Figure 6.6. Location of Dojo widget JavaScript file

When we open up the “TextBox.js” file we will find the following code near the top of the file.

          dojo.declare(
                  "dijit.form.TextBox",
                  dijit.form._FormWidget,

The dojo.declare function will be described in more detail in Chapter 12, “Objects and Classes,” when we discuss Object Orientation, but here’s a brief description of it now. The dojo.declare function creates a constructor function that can be used to build new objects. The first parameter is the name of that constructor function. The next parameter defines the super class for the object being created. The new object will inherit all the properties and methods from the super class. Additional code (not shown) describes properties and methods in the object created by the constructor. To create a new object after dojo.declare has been defined, you just use the standard JavaScript technique for object creation using the new keyword.

        newWidget = new dijit.form.TextBox();

The variable newWidget will now reference a JavaScript object. This object is not the DOM element itself, but a separate object associated with the Dojo widget. Like the wave/particle duality of light, Dojo widgets also have a dual nature existing as both a DOM element and a JavaScript object. As we’ve already discussed, there are two ways to create a Dojo widget—declaratively by including HTML markup or programmatically by using the new keyword as the preceding example shows. When we’re creating the widget using HTML markup, the Dojo parser automatically creates the widget object for us. So in both cases, the widget object is built from the constructor, but when using HTML markup, we don’t have to write the code ourselves.

What kinds of properties and methods are included in the constructor code? It all depends on the specific functionality of the widget. Each widget constructor is different, but there are some common characteristics. They all contain the following types of properties and methods:

We talk about the specific properties and methods for Dojo widgets when we review each widget in subsequent chapters. But there are some specific examples of these components that all widgets share, which we can discuss now.

There are many different kinds of Dojo widgets available to us. And although each type of widget is unique, they share many common features. To understand how a widget acquires these shared features, we need to understand a little about an object-oriented programming concept called inheritance. This is the idea that we can build new objects by inheriting the capabilities of existing objects. All Dojo widgets have some similarities. One of the most important ways they are similar is that they all descend from a few classes from which they inherit a number of special properties and methods. In object-oriented programming languages, these special ancestor objects are knows as abstract objects because they can’t be built into usable objects themselves. They are not standalone widgets but act as placeholders for inheritable properties and methods.

Let’s review Figure 6.7, which allows us to visualize the various widget classes and their relationships.

Figure 6.7. Dojo widget hierarchy

The diagram shows the overall relationship between the major widget classes. The diagram only shows a highly selective and abbreviated description of the class hierarchy for widgets. We’ll drill down more into these in later chapters. But I think it would be helpful now to at least get a brief description of some of the classes shown in the diagram.

Figure 6.7 contains many other widget classes besides those just described. We discuss these in detail in Chapters 7, 8, and 9, but we should describe some of them now. We’ll start with the most important class, dijit._Widget.

//mixin our passed parameters
if(this.srcNodeRef && (typeof this.srcNodeRef.id == "string")){
    this.id = this.srcNodeRef.id;
}
if(params){
    dojo.mixin(this,params);
}

this.postMixInProperties();

if(!this.id){
    this.id=dijit.getUniqueId(this.declaredClass.replace(/./g,"_"));
}

dijit.registry.add(this);

this.buildRendering();

// Copy attributes listed in attributeMap into
// the [newly created] DOM for the widget.
. . .

if(this.domNode){
        this.domNode.setAttribute("widgetId", this.id);
}

this.postCreate();

// If srcNodeRef has been processed and removed
// from the DOM (e.g. TemplatedWidget) then delete it to allow GC.
if(this.srcNodeRef && !this.srcNodeRef.parentNode){
        delete this.srcNodeRef;
}

At this point it would be useful to see some of the widgets. This will give you a good idea of the breadth of the Dojo widget set. The widgets are divided into general categories that correspond to the way the widgets are packaged. Most of these widgets have numerous properties that can be set to enable additional functionality. We only show the simplest version of each widget just to give you an idea of what they do. We drill down into each widget in subsequent chapters and see their full power.

Many of these examples are modified versions of test pages available in the Dojo distribution directory at “dijit/tests.”

Form and Data Widgets

These widgets appear in the form package. Their basic purpose is to display some data and provide the user with a way of modifying that data that is appropriate for the data type.

Table 6.4. Examples of Form Widgets

Description	Example
Button This replaces the standard HTML button. It looks nicer and has a slightly better effect on rollover.
DropDownButton When this button widget is clicked, it will display whatever widget is defined as its child. In the example, the leftmost widget is the widget before it is clicked. The rightmost example shows the same widget after it has been clicked. It displays its child widget, which in this case is a ColorPalette but could be any valid widget (menus are very typical).
ComboButton This widget combines a regular Button widget with a DropDownButton widget, hence the name ComboButton. The leftmost example shows the widget before the down arrow is selected. The rightmost example shows the widget after the down arrow icon has been checked. The user can click either on the down arrow icon or on the button itself.
ToggleButton
This button looks the same as a regular Button but behaves differently. When the button is clicked, the button CSS as well as the icon CSS can change.
CheckBox
This replaces the standard HTML checkbox. It looks nicer and has a better check icon.
RadioButton
This replaces the standard HTML checkbox. The advantages are a nicer look and a better checked icon.
FilteringSelect This widget is an enhanced version of the HTML <select> tag. One improvement is that when text is typed in the field it will be used to “filter” possible values from the full list of data. In this example, typing i causes the widget to only display states that begin with “I.” The data list could be static (provided in the HTML page) or could be acquired from the server using Ajax.
NumberSpinner This is really just a text box for entering numbers but with a special feature: Up and down arrow keys can be used to increase or decrease the value instead of the person having to type it directly.
Slider This widget is also a replacement for a simple numeric text value, but instead of entering the number directly you drag an icon (the slider) across a bar of values. The value for the widget is determined by the position of the slider on the bar.
Textarea This widget is a replacement for the standard HTML <textarea> tag. The primary additional feature of this widget is that it “grows” vertically instead of “scrolls” vertically. As you type, the size of the box expands to hold the text rather than displaying scroll bars to the side.
TextBox This widget is a replacement for the <input type="text"> HTML tag.
ValidationTextBox This widget extends TextBox and adds various kinds of validations including those for dates, times, and numbers. Messages and prompts are automatically displayed.
DateTextBox This widget extends TextBox by providing the user with a calendar metaphor for selecting a date. The widget looks like a TextBox on the page, but when the field is in focus, a pop-up calendar appears. This is a complex widget possessing a number of controls that allow the user to sequence through days, weeks, or years. And, of course, the look is easily customized by the developer.

 

Layout Widgets

These widgets appear in the layout package.

Table 6.5. Examples of Layout Widgets

Description	Example
LayoutContainer This widget provides a technique for dividing the page into separate areas for placing content. The areas can be aligned to the “top,” “bottom,” “right,” or “left.” Think of this widget as a replacement for using a table to provide layout.
SplitContainer This widget allows the user to define different areas, either vertically or horizontally, that can contain content. Between the areas is a border dragged to change the relative sizes of the panes. Any content within a pane can be automatically reformatted. The callout is not part of the widget.
StackContainer This is a container that has multiple children but only displays a single child at a time. It usually depends on some external control (like the prior page and next page buttons in this example) to allow the user to trigger the display of a different child. Otherwise, it looks like a typical ContentPane.
AccordianContainer
This widget acts as a container for its children. Only one child at a time is displayed (as with the StackContainer). However, the controls are built into this widget and display as pane titles with an arrow icon that can be used to collapse the displayed content and expand the hidden content.
ContentPane This widget that acts as a container for other widgets and includes the capability for dynamically loading content using Ajax.
TabContainer This widget acts as a container for its children and only displays a single child at a time. However, just like the AccordianContainer, its controls are built in and appear as tabs. By selecting a particular tab, the content associated with that tab is displayed.

 

Other Specialized Widgets

These are other widgets.

Table 6.6. Examples of Other Specialized Dojo Widgets

Description	Example
InlineEditBox This widget displays text that will be highlighted when the user places the mouse over it. Clicking the highlighted text causes it to be replaced with a different widget that can be used for editing. In this example, the user clicks the word “running” in the first line, which is then replaced with a TextBox that the user can enter a new value in.
Menu This widget displays a popup menu that can be nested as deeply as the developer wants. Menu items can be separated with a line icon or disabled.
Toolbar
A toolbar presents a series of options or icons that can display additional content (including submenus) or trigger some process to occur.
ProgressBar This widget is used to represent the completion state of a process. In this example, the current state of the widget is shown as a number (i.e., 10%), and the bar is partially filled in at the left.
Tooltip This widget displays a popup.
TooltipDialog Pops up a dialog that appears like a Tooltip. It may contain any content including a form. The page behind the widget is still active.
Dialog
This widget provides a pop-up dialog containing content that may include a form (as shown in the example). When the dialog appears, the original page is disabled. This is sometimes known as a modal dialog. The page does not become active until the dialog is dismissed.
ColorPalette
This widget displays color swatches that can be selected by the user. The widget will automatically convert the selected color into its RGB value for use inside the page.
Tree This widget displays data in a hierarchical tree with nodes that can be expanded or collapsed. You can specify an icon for each node. One of the major features of the tree widget is the ability to build itself from data on the server by making Ajax requests when either the tree is first built or when nodes are expanded.

 

The visual guide provides a quick introduction to many of the widgets available to you in Dojo. However, there are some we didn’t cover, which we review in subsequent chapters. Also remember that Dojo is constantly being improved, and new widgets are becoming available all the time.

Dojo widgets are highly customizable. You can change the way they look by changing their style properties. You can control their behavior by setting properties and by providing overrides to the various life-cycle methods. However, sometimes you may just want to build your own widget. The various base classes such as dijit._Widget, dijit.form._FormWidget, and dijit.layout._LayoutWidget are perfect starting points for creating new widget classes of your own.

 <input type="text" dojoType="dijit.form.TextBox" />

 new dijit.form.TextBox({}, dojo.byId("placeHolder"));

 dojo.require("dijit.form.TextBox");

Now that we’ve seen how Dojo widgets work in general (and we’ve seen some examples of specific widgets), we can begin a detailed study of the various widgets available in Dojo. The next chapter explores each of the Form widgets in detail.