As anyone who's ever touched a computer knows, HTML is the de facto standard for displaying information in a web browser. You can standardize headings, paragraph division, form fields, and generally provide just about any kind of markup that's useful for displaying textual information and images. Still, HTML alone isn't very pleasing to the eye: there's no nice formatting involved, and the content is static. The overall structure of a page is quite simple, and it doesn't change in response to user interaction. Given what we've come to expect over the years, the web would be intolerably boring with HTML alone.

Bring in a dash of CSS, however, and the scene changes significantly. Suddenly, the aesthetic nature of the page improves. Whereas HTML alone provides content with very little visual appeal, CSS adds value by improving a page's layout and typesetting. But style alone still results in a static page that leaves the inherent dynamism of human interaction longing for something with a little more life. You could create some nicely typeset pages with HTML and CSS, but that's about it.

JavaScript provided the dynamism that styled HTML so sorely lacked and gave rise to DHTML, which fueled the increasingly interactive online experience that blossomed into this modern era of rich Internet applications. JavaScript brings a web page to life and enables that sheer contentment we enjoy when a simple mouse click, selection in a combo box, or casual keystroke makes you wonder if the computer is reading your mind.

Although we've all come to know a well-designed, interactive web page when we see one, the experience itself can still be quite difficult to achieve; the JavaScript that controls the HTML and CSS can often be quite complex, and even the cleverest of implementations may not be maintainable or especially noteworthy. The central issue at stake is that the HTML, CSS, and JavaScript can be difficult to integrate into a single, cohesive framework. With little cohesion amongst them in ad-hoc designs, synergy is difficult to achieve, and massive amounts of energy is lost in implementing the not-so-interesting boilerplate. Unfortunately, this laborious process can quickly drain motivation and creativity from the parts of the application that really matter.

Fortunately, dijits make matters much easier by providing the foundation upon which you can build a more complex design. They unite the HTML, CSS, and JavaScript into a unified medium, and although not perfect, dijits allow you to think in an object-oriented context much more quickly than you would without them: the end result is that you can quickly get to the heart of your own application before so much of the energy and creativity dries up. Whereas you previously had to provide your own means of uniting the HTML, CSS, and JavaScript, Dojo now does that tiresome work for you, and leaves you to get to the good stuff more quickly.

Just like standalone classes, dijits are self-contained inside of a single directory that corresponds to a namespace. In addition to a single JavaScript file, however, the directory also contains dependencies such as image file and stylesheets. The inherent familiarity of a directory structure provides an innate portability that makes it trivial to share, deploy, and upgrade dijits. Maintenance is also eased because there are no binary formats to unravel, and each component of a dijit can be checked into a version control system like Subversion as a separate file.

While all of the resources that compose a dijit could just be thrown into a single directory in the one-big-pair-of-clown-pants approach, Figure 12.1, “Anatomy of a dijit on disk” displays a common convention for laying out a dijit on disk. Basically, the convention is to just compartmentalize the various facets into subdirectories to make things more manageable.

Figure 12.1. Anatomy of a dijit on disk

Dijits unite the HTML, CSS, and JavaScript that are so very central to any web development effort and provide you with a single, unified means of structuring the creativity required of your own application. In the end, you'll save time, effort, and likely obtain a more efficient design. Note that the layout for a minimal dijit that doesn't include a template or CSS is simply a directory with a JavaScript file.

The layout shown in Figure 12.1, “Anatomy of a dijit on disk” shows the template contained in its own separate HTML file, and this setup is typical during the development cycle because it allows members of the development team to work on the template, CSS, and JavaScript files separately.

Fetching the template requires the JavaScript engine to issue a synchronous call back to the server; however, Dojo provides a wonderful way to optimize that synchronous call out the picture entirely: you can include the template as an inline string that's inside of the JavaScript file. Plenty of examples are coming up that illustrate how simple it is to make this happen.

To come full circle to the discussion about the creation pattern dojo.declare provides from back in Chapter 10, Simulated Classes and Inheritance, here's how the _Widget lifecycle plugs in:

preamble(/*Object*/ params, /*DOMNode*/node)
     //precursor to constructor; can manipulate superclass constructor args

constructor(/*Object*/ params, /*DOMNode*/node)
    // fire any superclass constructors
    // fire off any mixin constrctors
    // fire off the local class constructor, if provided

postscript(/*Object*/ params, /*DOMNode*/node)
    //_Widget implements postscript to kick off the create method...
    _Widget.create(/*Object*/params, /*DOMNode*/node)
    _Widget.postMixInProperties(  )
    _Widget.buildRendering(  )
    _Widget.postCreate(  )

The take away is two-fold:

dojo.require("dijit._Widget");
dojo.addOnLoad(function(  ) {
    dojo.declare(
      "dtdg.Foo",
      dijit._Widget,
      {
        talk(  ) : function(  ) {
          console.log("id:", this.id);
          console.log("lang:", this.lang);
          console.log("dir:", this.dir);
          console.log("domNode:", this.domNode);
        }
      }
    );
});
foo = new dtdg.Foo(  );
foo.talk(  );

While _Widget provides the foundational stub methods that you can override for creation and destruction events that occur during the lifecycle, _Templated is the previously alluded-to ancestor that actually provides the basis for defining a widget's template in markup and using substitutions and attach points to add functionality to it. Overall, it's a nice separation that lends itself to tooling and separates designer tasks from coding.

The vast majority of _Templated 's work involves parsing and substituting into a template file. An important part of this work entails overriding _Widget 's buildRendering method, which is where all of the template mangling takes place. Three very important concepts for templates include:

Like _Widget, _Templated is given more thorough coverage with some isolated examples in just a moment. You're being exposed to it now so that you have a general idea of its overall purpose.

The first take on the HelloWorld dijit provides the full body of each component. For brevity and clarity, subsequent iterations provide only relevant portions of components that are directly affected from changes. As far as on disk layout, these examples assume that the main HTML file that includes the widgets is located alongside a dtdg module directory that contains the widget code.

<html>
  <head>
    <title>Hello World, Take 1</title>

<!--
   Because Dojo is being served from AOL's server, we have to provide a
   couple of extra configuration options in djConfig as the XDomain
   build (dojo.xd.js) gets loaded.

   Thus, we associate the "dtdg" namespace w/ a particular relative path
   on disk by specifying a baseUrl along with a collection of namespace mappings.
   If we were using a local copy of Dojo, we could simply stick the
   dtdg directory beside the dojo directory and it would have been
   found automatically.

   Specifying that dijits on the page should be parsed on page load
   is normally standard for any situation in which you have dojoType tags in the page.

-->
  <script
    type="text/javascript"
    src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js"
    djConfig=isDebug:true,parseOnLoad:true,baseUrl:'./',modulePaths:{dtdg:'dtdg'}">
  </script>

<!--
    You'll normally include the dojo.css file, followed by
    any of your own specific style sheets. Remember that if you're not using
    AOL's XDomain build, you'll want to point to your own local dojo.css file.
-->
<link
    rel="stylesheet"
    type="text/css"
    href="http://o.aolcdn.com/dojo/1.1/dojo/resources/dojo.css">
</link>

<link
    rel="stylesheet"
    type="text/css"
    href="dtdg/themes/hello/hello.css">
</link>

<script type="text/javascript">

    dojo.require("dojo.parser");

    //Tell Dojo to fetch a dijit called HelloWorld that's associated
    //with the dtdg namespace so that we can use it in the body.
    //Dojo will use the values in djConfig.modulePaths to look up the location.
    dojo.require("dtdg.HelloWorld");
</script>
</head>
<body>
    <!--
    This is where the Dojo parser swaps in the dijit from the
    dojo.require statement based on our parseOnLoad:true option.
    Any styles applied to the dijit are provided by the style sheets imported.
    -->
    <div dojoType="dtdg.HelloWorld"></div>
</body>
</html>

div.hello_class {
    color: #009900;
}

<div class="hello_class">Hello World</div>

//Summary: An example HelloWorld dijit that illustrates Dojo's basic dijit
//design pattern

//The first line of any module file should have exactly one dojo.provide
//specifying the resource and any membership in parent modules. The name
//of the resource should be the same as the .js file.
dojo.provide("dtdg.HelloWorld");

//Always require resources before you try to use them. We're requiring these
//two resources because they're part of our dijit's inheritance hierarchy.
dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

//The feature rich constructor that allows us to declare Dojo "classes".
dojo.declare(
    "dtdg.HelloWorld",

    //dijit._Widget is the prototypical ancestor that provides important method
    //stubs like the ones below.
    //dijit._Templated is then mixed in and overrides dijit._Widget's
    //buildRendering method, which constructs the UI for the dijit from
    //a template.
    [dijit._Widget, dijit._Templated],
    {
        //Path to the template of this dijit. dijit._Templated uses this to
        //snatch the template from the named file via a synchronous call.
        templatePath: dojo.moduleUrl("dtdg", "templates/HelloWorld.html")
    }
);

Suppose you want your dijit to be a little less generic. Instead of displaying the same static message every time the page is loaded, a good first step might be to make the custom message that is displayed dynamic. One of the wonderful mechanisms that Dojo employs for keeping the logical concept of a dijit cohesive is that you can reference dijit properties that are defined in your JavaScript source file inside the template. Although referencing dijit properties from inside the template is only useful prior to _Templated 's buildRendering method executing, you'll find that initializing some portion of a dijit's display before it appears on the screen is a very common operation.

Referencing a dijit property from inside of the template file is simple. Consider the following revision to the HelloWorld template file:

<div class="hello_class">${greeting}
</div>

In short, you can refer to any property of the dijit that exists from inside of the template file and use it to manipulate the initial display, style, etc. However, there is a small but incredibly important catch: you have to do it at the right time. In particular, dijit properties that are referenced in templates are almost always most appropriately manipulated in the postMixInProperties method. Recall that postMixInProperties is called before buildRendering, which is the point at which your dijit gets inserted into the DOM and becomes visible.

Without further ado, Example 12.3, “HelloWorld (Take 2: postMixInProperties)” shows how the dijit's JavaScript file should appear if we want to manipulate the properties in the template to display a custom greeting.

//An example of properly manipulating a dijit property referenced
//in a template string via postMixInProperties
dojo.provide("dtdg.HelloWorld");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare(
        "dtdg.HelloWorld",
        [dijit._Widget, dijit._Templated],
    {
        greeting : "",

        templatePath: dojo.moduleUrl(
            "dtdg",
            "templates/HelloWorld.html"
        ),

        postMixInProperties: function(  ) {
            //Proper manipulation of properties referenced in templates.
            this.greeting = "Hello World"; //supply as static greeting.
        }
    }
);

As alluded to earlier, you can save a synchronous call back to the server by specifying the template string directly inside of your JavaScript file. The next variation on the HelloWorld in Example 12.4, “HelloWorld (Take 3: templateString)” demonstrates just how easy this is to do manually, but keep in mind that the Dojo build scripts found in Util can automate this process for all of your dijits as part of a deployment routine.

dojo.provide("dtdg.HelloWorld");
dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare(

    "dtdg.HelloWorld",
    [dijit._Widget, dijit._Templated],
    {
        greeting : "",

        //Provide the template string inline like so...
        templateString : "<div class='hello_class'>${greeting}</div>",

        postMixInProperties: function(  ) {
            console.log ("postMixInProperties");

            //We can still manipulate the template string like usual
            this.greeting = "Hello World";
        }
    }
);

In this example, templateString provides the template inline, so there's no need for a separate template file. This, in turn, saves a synchronous call to the server. If you can imagine lots of dijits with lots of template strings, it's pretty obvious that baking the template strings into the dijit's JavaScript files can significantly reduce the time it takes to load a page. For production situations, you won't want to do without the Util's build system (Chapter 16, Build Tools, Testing, and Production Considerations) to automate these kinds of performance optimizations for you.

As yet another improvement to our HelloWorld dijit, let's learn how to pass in custom parameters to dijits through the template. Given the previous example, let's suppose that we want to supply the custom greeting that is to appear in our widget from its markup that appears alongside the dojoType tag. Easy; just pass it in like so:

<div dojoType="dtdg.HelloWorld" greeting="Hello World"
></div>

Passing in the parameter for a widget that is programmatically created is just as simple:

var hw = new dtdg.HelloWorld({greeting :  "Hello World"
}, theWidgetsDomNode);

Of course, you are not limited to passing in values that are reflected in the template. You can pass in other parameters that are used in other ways as well. Consider the following DIV element containing a reference to your HelloWorld dijit that specifies two extra key/value pairs:

<div foo="bar" baz="quux" dojoType="dtdg.HelloWorld"></div>

Wouldn't it be handy to be able to pass in custom data to dijits like that so that they can use it for initialization purposes—allowing application-level developers to not even have to so much as even peek at the source code and only hack on the template a bit? Well, ladies and gentlemen, you can, and the JavaScript file in Example 12.5, “HelloWorld (Take 4: custom parameters)” illustrates just how to do it.

dojo.provide("dtdg.HelloWorld");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare(
        "dtdg.HelloWorld",
        [dijit._Widget, dijit._Templated],
    {
        templateString : "<div class='hello_class'>Hello World</div>",

        foo : "",

        //you can't set dijit properties that don't exist
        //baz : "",

        //tags specified in the element that supplies the dojoType tag
        //are passed into the constructor only if they're defined as
        //a dijit property a priori. Thus, the baz="quux" has no effect
        //in this example because the dijit has no property named baz
        constructor: function(  ) {

            console.log("constructor: foo=" , this.foo);
            console.log("constructor: baz=" , this.baz);
        }

    }
);

As you might have noticed, there's an emphasis on making the point that you can only pass in values for dijit properties that exist ; you cannot create new dijit properties by tossing in whatever you feel like into the element that contains the dojoType placeholder tag. If you run the previous code example and examine the Firebug console, you'll see the following console output:

constructor: foo=bar
constructor: baz=undefined

While passing in string values to dijits is useful, string values alone are of limited utility because life is usually just not that simple—but not to worry: Dojo allows you to pass in lists and associative arrays to dijits as well. All that is required is that you define dijit properties as the appropriate type in the JavaScript file, and Dojo takes care of the rest.

The following example illustrates how to pass lists and associative arrays into the dijit through the template.

Including the parameters in the element containing the dojoType tag is straightforward:

<div
   foo="[0,20,40]"
   bar="[60,80,100]"
   baz="{'a':'b', 'c':'d'}"
   dojoType="dtdg.HelloWorld"
></div>

And the JavaScript file is just as predictable:

dojo.provide("dtdg.HelloWorld");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare(

        "dtdg.HelloWorld",

        [dijit._Widget, dijit._Templated],

    {
        templateString : "<div class='hello_class'>Hello World</div>",

        foo : [], //cast the value as an array
        bar : "", //cast the value as a String
        baz : {}, //cast the value as an object

        postMixInProperties: function(  ) {
            console.log("postMixInProperties: foo[1]=" , this.foo[1]);
            console.log("postMixInProperties: bar[1]=" , this.bar[1]);
            console.log("postMixInProperties: baz['a']=",  this.baz['a']);
        }

    }
);

Here's the output in the Firebug console:

postMixInProperties: foo[1]=20
postMixInProperties: bar[1]=6
postMixInProperties: baz['a']=b

Note that even though the value associated with the dijit's property bar appears to be a list in the page that includes the template, it is defined as a string value in the JavaScript file. Thus, Dojo treats it as a string, and it gets sliced as a string. In general, the parser tries to interpret values into the corresponding types by introspecting them via duck typing.

As yet another variation on our HelloWorld dijit, consider the utility in associating a DOM event such as a mouse click or mouse hover with the dijit. Dojo makes associating events with dijits easy. You simply specify key/value pairs of the form DOMEvent: dijitMethod inside of a dojoAttachEvent tag that appears as a part of your template. You may specify multiple key/value pairs or more than one kind of native DOM event by separating them with a comma.

Let's illustrate how to use dojoAttachEvent by applying a particular style that's defined as a class in a stylesheet whenever a mouseover event occurs and remove the style whenever a mouseout event occurs. Because DIV elements span the width of the frame, we'll modify it to be an inline SPAN, so that the mouse event is triggered only when the cursor is directly over the text. Let's apply the pointer style to the cursor.

The changes to the style are simple. We change the reference to an inline SPAN instead of a DIV and change the mouse cursor to a pointer:

span.hello_class {
    cursor: pointer;
    color: #009900;
}

The JavaScript file in Example 12.6, “HelloWorld (Take 5: dojoAttachEvent)” includes the updated template string, illustrating that the use of dojoAttachEvent is fairly straightforward as well.

dojo.provide("dtdg.HelloWorld");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare(
        "dtdg.HelloWorld",
        [dijit._Widget, dijit._Templated],
    {
        templateString :
        "<span class='hello_class' dojoAttachEvent='onmouseover:onMouseOver,
onmouseout:
        onMouseOut'>Hello World</span>",

        onMouseOver : function(evt) {
            dojo.addClass(this.domNode, 'hello_class');
            console.log("applied hello_class...");
            console.log(evt);
        },

        onMouseOut : function(evt) {
            dojo.removeClass(this.domNode, 'hello_class');
            console.log("removed hello_class...");
            console.log(evt);
        }

    }
);

See how easy that was? When you trigger an onmouseover event over the text in the SPAN element, style is applied with the dojo.addClass function, which is defined in Base. Then, when you trigger an onmouseout event, the style is removed. Neat stuff!

Did you also notice that the event handling methods included an evt parameter that passes in highly relevant event information? As you might have guessed, internally, dojo.connect is at work standardizing the event object for you. Here's the Firebug output that appears when you run the code, which also illustrates the event information that gets passed into your dijit's event handlers:

applied hello_class...
mouseover  clientX=64, clientY=11
removed hello_class clientX=65, clientY=16
mouseover  clientX=65, clientY=16

To be perfectly clear, note that the previous example's mapping of onmouseover to onMouseOver and onmouseout to onMouseOut is purely a simple convention, although it does make good sense and results in highly readable code. Also, it is important to note that events such as onmouseover and onmouseout are DOM events, while onMouseOver and onMouseOut are methods associated with a particular dijit. The distinction may not immediately be clear because the naming reads the same, but it is an important concept that you'll need to internalize during your quest for Dijit mastery. The semantics between the two are similar and different in various respects.