The kernel of Dojo is Base, an ultra-compact, highly optimized library that provides the foundation for everything else in the toolkit. Among other things, Base provides convenient language and AJAX utilities, a packaging system that allows you to pull in Dojo resources on-the-fly instead of requiring them to all be slurped in when the page loads. It also supplies you with tools for creating and manipulating inheritance hierarchies, a means of almost universally querying the DOM using CSS3 selectors, and a fabric that standardizes DOM events amongst various browsers. Everything that Base provides is available in the top level of the toolkit's namespace as a dojo.* function or attribute. Base comes packaged as a single file, dojo.js, which comes across the wire at under 30KB, and when you consider that most Flash-based advertisements that inundate the web are considerably larger than 30KB, such a small number seems quite amazing.

One other really interesting thing about Base is that it is designed to bootstrap the Dojo essentials automatically by simply including the dojo.js file into the page. To oversimplify things a bit, bootstrapping basically entails detecting the environment, smoothing out browser incompatibilities, and loading the dojo namespace. Various configuration options can also be specified to automatically parse any widgets in the page and perform other initialization tasks. (All coming up in future chapters.)

Base provides a tremendous wealth of utility for many standard operations you'll commonly need to achieve when doing just about anything in JavaScript. Even if you don't use anything else in the toolkit, Base will probably be a valuable resource that you won't want to live without once you've experienced the productivity boost it provides. There is no Dojo without Base; everything in the toolkit depends or builds on it one way or another.

Core builds on Base by offering additional facilities for parsing widgets, advanced animation effects, drag-and-drop facilities, internationalization (i18n), back-button handling, managing cookies, and more. Resources available through Core are often used frequently and provide fundamental support for common operations, but were not deemed universal enough to include in Base. Although the distinction between what did and didn't make it into Core may not be a perfect boundary, Dojo's packaging system trivializes the amount of effort required to pull in additional modules and resources as needed with a simple mechanism that works like a #include from C or an import statement from Java.

In general, distinguishing between Base and Core is simple: any module or resource that you have to explicitly import into the page external to dojo.js is a part of Core if it is associated with the dojo namespace. Core facilities usually do not appear in the Base level namespace, and instead appear in a lower-level namespace such as dojo.fx or dojo.data.

Describing Dojo as just a JavaScript standard library of sorts would only be telling you a small part of its story; Dojo also packs a fantastic library of widgets called Dijit (short for "Dojo widget") that is ready to use out of the box and often doesn't require you to write any JavaScript at all. Dijits conform to commonly accepted accessibility standards such as ARIA^[7] and come with preconfigured internationalization that spans many common locales. Dijit is built directly upon Core (providing a strong testament to Core's integrity), so whenever you need a custom widget of your own devising, you'll be using the very same building blocks that were used to create everything else in Dijit. The widgets that you create with Dojo are ultra-portable and can easily be shared or deployed onto any web server or often even run locally without a web server at all via the file:// protocol.

Plugging a dijit into a page is as easy as specifying a special dojoType tag inside of an ordinary HTML tag—a dream come true for layout designers and users who aren't interested in doing a lot (or any) JavaScript programming. In fact, a key benefit of using Dijit for application developers is that it allows you to achieve incredibly rich functionality without having to dig into tedious implementation details. Even if you're more of a library-writing type or a custom widget developer, following Dijit's style and conventions ensures that your widgets will be portable and easy to use—essentials for any reusable software component.

The Dijit battery can be roughly divided into general-purpose application widgets like progress bars and modal dialogs, layout widgets like tab containers and accordion panes, and form widgets that provide super-enhanced versions of old hats like buttons and various input elements.

DojoX is a collection of subprojects that officially stands for "Dojo Extensions," although it is often called "Extensions and Experimental." The "extensions" subprojects in DojoX accounts for stable widgets and resources that while extremely valuable just don't fit nicely into Core or Dijit; the "experimental" subprojects account for widgets that are highly volatile and in more of an incubation stage.

Each DojoX subproject is required to come with a README file that contains a synopsis of its status. Although DojoX subprojects strive to meet accessibility and internationalization initiatives consistent with Dijit, it is not generally the case that they're always quite that refined. Be that as it may, lots of heavy machinery for real world applications lives in DojoX, including the grid widget, data converters for common web services, etc. DojoX also provides a sandbox and incubator for fresh ideas, while simultaneously ensuring that the high standards and stable APIs for resources in Core and Dijit are not compromised. In that regard, DojoX strikes a sensitive balance for critical issues central to any community-supported OSS project.

Util is a collection of Dojo utilities that includes a JavaScript unit-testing framework and build tools for creating custom versions of Dojo for production settings. The unit-testing framework, DOH,^[8] does not have a specific coupling to Dojo and provides a simple set of constructs that can be used to automate quality assurance on any JavaScript code. After all, you do want to implement well-defined, systematic tests for your JavaScript code, don't you?

The essence of the build tools is that they shrink the size of your code and can aggregate into a set of layers, where each layer is nothing more than a collection of other JavaScript files. The compression is accomplished via ShrinkSafe, a patched version of Mozilla's powerful Rhino JavaScript engine that compresses JavaScript code without mangling public APIs, and the aggregation is accomplished with a collection of custom scripts that are also run by Rhino. Other auxiliary components in Util do things like inline HTML template strings (more on this when Dijit is formally introduced in Chapter 11, Dijit Overview) into JavaScript files—another trick for reducing latency.

Like DOH, ShrinkSafe may be used independently of Dojo, and for production settings there is almost never a good reason not to use it, given that it is not uncommon for it to reduce the JavaScript footprint by 50% or more. The performance difference between loading many large JavaScript files via a series of synchronous requests and retrieving one or two compressed JavaScript files can be quite staggering.

There are three primary ways you can use Dojo: downloading an official release to your local environment, checking out a copy from Subversion to your local environment, and using an XDomain build from AOL's CDN. This section walks you through each of these options.

svn co http://svn.dojotoolkit.org/src/view/anon/all/trunk ./svn

<script
    type="text/javascript"
    src="www/js/dojo/dojo.js">
</script>

<script
    type="text/javascript"
    src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js">
</script>

If you've done even a trivial amount of web development, you already know that debugging can sometimes be quite painful, especially when it involves obscure differences between browsers or deviations from the W3C standards. Unfortunately, throwing in a toolkit that wields a lot of power and complexity of its own can sometimes make debugging even tougher, and this might especially be the case for the JavaScript realm that involves the dynamism of closures, dynamic typing, and inconvenient ways of producing debug messages with alert boxes. And then there was Firebug, an amazing Firefox extension that made debugging and web development a lot easier.

As a rule of thumb, you should strongly consider developing in Firefox, because Firebug in and of itself is nothing short of incredible in terms of speeding up the development cycle. You can inspect/manipulate anything in the DOM (including style) in real time, log events to the Firebug console, and get error information that's often specific enough to identify your actual problem. (Compare that to a brilliant alert box that asks, "Would you like to debug?")

Of course, do remember to verify that your design is truly cross-platform by frequently sanity testing in IE and other browsers. Although Dojo itself goes to great lengths to work around browser quirks, it is still possible that anomalies can occur—and the sooner you discover these, the better.

Be advised that Dojo aims to integrate as tightly with Firebug as possible, so it comes packaged with Firebug Lite. Thus, even if you must develop in another browser, functions such as console.log are always available to you if you want them.

You can download Firefox and Firebug from http://www.getfirefox.com and http://www.getfirebug.com, respectively. Appendix A, A Firebug Primer contains a Firebug tutorial that you may find helpful for development.

Most of the examples in this book are designed to loaded from a locale file:// protocol, which generally works fine. However, it appears that users of Firefox 3 may need to make one small adjustment to load Dojo locally:

You can read more about this issue at http://kb.mozillazine.org/Security.fileuri.origin_policy.

Almost all of the content in this book can be demonstrated without a web server. To adequately demonstrate a select few pieces of the toolkit, however, it is helpful to serve up some dynamic content coming from a server. When these times arise, we'll use CherryPy (version 3.1+), an extremely easy-to-use web server that's written in Python. You can download and read all about CherryPy at http://cherrypy.org, but don't fret, you won't be derailed on your Dojo learning efforts by getting all bogged down with the details of having to learn about a new web server.

Installing CherryPy is as simple as downloading it and following a few short instructions in the README file. CherryPy installs just like any other Python module, so there isn't an exposed installation directory, per se. Unlike other, heftier server-side technologies, CherryPy just becomes readily available for you to use whenever you include it via an import statement like other Python modules. In fact, a CherryPy application is nothing more than a standalone Python application that is running its own multithreaded web server; thus, actually executing a "server-side script" is as simple as running a single command in a terminal.

For example, if you were asked to invoke the following simple application stored in a file called hello.py, you'd do nothing more than type python hello.py on the command line. That's all that it takes to have CherryPy start up and listen on port 8080 for incoming requests. Having already installed CherryPy, the import cherrypy statement shown in Example 1.1, “A very simple CherryPy application” locates it and makes it available for use.

1 import cherrypy
2
3 class Content:
4
5     @cherrypy.expose
6     def index(self):
7         return "Hello"
8
9     @cherrypy.expose
10     def greet(self, name=None):
11         return "Hello "+name
12
13  cherrypy.quickstart(Content(  ))

For Example 1.1, “A very simple CherryPy application”, if you navigate to http://localhost:8080/ in your web browser, you would access the index method (lines 6–7) and get back the response "Hello", whereas if you navigate to http://localhost:8080/greet?name=Dojo, you'd access the greet method (lines 10–11), which processes the name query string parameter and gives back the response "Hello Dojo". That's the general pattern, and given how inherently readable Python code is, it can't get much easier than that.

While you'll never need to write or understand Python code to this book, the previous walk-through was included just to show you how quick and easy it is to do with CherryPy and Python in case you ever need or want create dynamic content of your own. Learning Python by Mark Lutz (O'Reilly) is a great reference on Python if you find yourself ever needing to work up more complex Python code. Python's official web presence at http://www.python.org and CherryPy's web site at http://www.cherrypy.org have great documentation as well.

Because dojo.require statements act asynchronously over XDomain loads, it is not necessarily safe to immediately use resources you have requested via dojo.require when the page loads^[9] because latency and other factors may (and usually will) cause some delay. Then, when you try to reference a module requested via dojo.require that is not yet loaded, you get a nice error thrown at you and the entire bootstrapping process most likely screeches to a halt. The technical term for the situation in which the outcome is undefined because of unpredictable timing constraints that compete with one another is called a race condition.

For the reasons just mentioned, using dojo.addOnLoad is a very good habit to get into because it makes your page as portable as possible—whether or not it is XDomain-loaded.

Given that the previous code snippet uses XDomain loading, there aren't any extra steps involving local installation, so it really is a one-step process to bootstrap the entire toolkit from an existing page.

While bootstrapping is synonymous with "loading a script" at a high level, there's a lot more happening with that loading process than meets the eye. From a bird's eye view, at least two basic actions occur, though not necessarily in this exact order:

Upcoming sections introduce djConfig, a configuration switch that you can place in the SCRIPT tag that bootstraps the toolkit (or define anytime before Dojo bootstraps) to customize where it looks for resources, whether debugging tools should be wired in, and so on.

Table 1.1, “djConfig configuration switches” provides a synopsis of the key/value pairs you can pass into it to configure the bootstrapping process. (Some of the commentary may introduce constructs that have not yet been introduced. For now, just skim over those and come back to them whenever the occasion calls for it.)

Most of the time, you will define djConfig in the same SCRIPT tag that bootstraps the toolkit using Object -like syntax. The following example illustrates:

<script
    type="text/javascript"
    src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js"
    djConfig="parseOnLoad:true,isDebug:true">
</script>

However, you might opt to define it prior to the SCRIPT tag that loads the toolkit if you have a lot of configuration switches, or if it's just more convenient to do it that way for your particular situation. Here's a translation of the previous example that produces the very same effect:

<script type="text/javascript">
    djConfig = {
        parseOnLoad : true,
        isDebug : true
    };
</script>

<script
  type="text/javascript"
  src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js ">
</script>

To illustrate, transcribe the minimalist HTML page in Example 1.3, “A really simple HTML page for illustrating a few features from Base” into a local file to get started. The only Dojo-specific nuance is the script tag that performs the XDomain loading. Although we haven't covered the djConfig parameter that you'll see is included in the SCRIPT tag, it's just a way of passing in configuration information to Dojo as it bootstraps. In this case, we're specifying that debugging facilities such as the Firebug console should be explicitly available to us. Even if you're using another browser such as IE, the djConfig="isDebug:true" option ensures that Firebug Lite is loaded.

<html>
     <head>
         <title>Fun with Dojo!</title>

            <link rel="stylesheet"  type="text/css"
              href="http://o.aolcdn.com/dojo/1.1/dojo/resources/dojo.css" />

         <script
              type="text/javascript"
              src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js"
             djConfig="isDebug:true">
        </script>

        <style type="text/css">
              .blue {color: blue;}
        </style>
    </head>
     <body>
        <div id="d1" class="blue">A div with id=d1 and class=blue</div>
        <div id="d2">A div with id=d2</div>
        <div id="d2">Another div with id=d2</div>
        <div id="d4">A div with id=d3.
            <span id="s1">
                This sentence is in a span that's contained in d1.
                The span's id is s1.
            </span>
        </div>
         <form name="foo" action="">
             A form with name="foo"
         </form>
          <div id="foo">
             A div with id=foo
          </div>
      </body>
</html>

Once you've saved out the file, open the page in Firefox, and click on the little green circle with the checkmark in it to expand the Firebug console. Then, click on the caret icon just beside Firebug's search box to open up Firebug in a new window, as shown in Figure 1.2, “Firebug reveals valuable information that you can use to sanity check what is happening with network requests, and more”. (If you haven't read the primer on Firebug in Appendix A, A Firebug Primer, this would be a good time to divert and do so.) Clicking on the "Net" tab reveals that the XDomain dojo.xd.js file consisting of Base has indeed been downloaded from the CDN.

Figure 1.2. Firebug reveals valuable information that you can use to sanity check what is happening with network requests, and more

If you click back on the "Console" tab and type dojo on the >>> prompt followed by the enter key, you should see a Firebug console message that says something along the lines of Object global=window isBrowser=true isRhino=false, which shows you that the global JavaScript object dojo is indeed alive and well. Typing in console.dir(dojo) would provide an exhaustive tree-view of everything that's contained in Dojo. Although you'll also see a lot of private members that are prefixed with a leading underscore, go ahead try it out for yourself. Skimming the contents of the output will give you a small taste of what's packed up inside of Base.

dojo.byId

Dojo provides dojo.byId as a drop-in replacement for document.getElementById. Thus, passing in a string value like dojo.byId("s1"), for example, shows that it returns a reference that you could store in a variable just like you could with a call to document.getElementById. However, in addition to looking up an id value, dojo.byId also acts like a no-op if you pass it a DOM node. Internally, the function introspects its argument, so on the application level, you don't have to even think twice. Its complete function signature looks like this:

dojo.byId(/*String*/ id | /*DomNode*/ node)  // Returns a DOM Node

Tip

Throughout the book, the pipe, |, is used to denote the logical "or" operation in function signatures whenever there is more than one possibility.

Because it appears that dojo.byId does almost the very same thing as document.getElementById, you may be tempted to just forget about dojo.byId all together—but don't! As it turns out, it smooths out some subtle inconsistencies that might just burn you when you least expect it. One well-known bug for document.getElementById surfaces IE6 and IE7. To illustrate, type the following into the Firebug Lite console for the sample document we're working on, and you'll see Figure 1.3, “The resulting behavior of document.getElementById versus dojo.byId for the previous document”:

Figure 1.3. The resulting behavior of document.getElementById versus dojo.byId for the previous document

document.getElementById("foo") //Isn't the answer *so* obvious?!?

Hmm. You probably didn't expect to have the FORM element returned, did you? As it turns out, if it had not appeared first in the document, you should have gotten the div element returned. This particular bug arises because the name and id attribute namespaces are merged for IE. So much for cross-browser compatibility on the obvious things in life! Figure 1.4, “Dojo makes your code more portable by insulating you from browser quirks” shows how Dojo protects you from the cold hard metal of the browser, saving you from working around the multitude of inconsistencies that would otherwise prevent your application from being portable.

Figure 1.4. Dojo makes your code more portable by insulating you from browser quirks

But in addition to dojo.byId working around that particular quirk, dojo.byId also returns the first element if more than one element has an id set to the same value, thereby normalizing corner case behavior. For our example document, you can verify that dojo.byId always returns the first element by trying out the following statement:

dojo.byId("d2").innerHTML

More than anything else, the takeaway from this short lesson is that if you're developing with a JavaScript toolkit, use its API to get work done instead of ways you may have learned with raw JavaScript. Occasionally, you may see an API call that doesn't seem to add any additional value, and the temptation may be to fall back to your own tried-and-true method of getting something accomplished—but resist the temptation! Well-designed APIs do not provide useless functionality.

Warning

Viewing an API call as "worthless" may be an indication that you may be confused about the exact utility that the call provides. Whenever this happens, review the documentation to find out what it is you're missing. If the documentation still doesn't convince you, hop on a mailing list or IRC channel and ask someone about it.

connect(/*Object|null*/ obj,
        /*String*/ event,
        /*Object|null*/ context,
        /*String|Function*/ method) // Returns a connection handle

var handle = dojo.connect(
  dojo.byId("s1"), //context
  "onmouseover", //event
  null, //context
  function(evt) {console.log("mouseover event", evt);} //event
);

var handle = dojo.connect(
  dojo.byId("s1"), //context
  "onmouseover", //event
  function(evt) {console.log("mouseover event",evt);} //event
);

dojo.disconnect(handle);

dojo.query("div") //find all of the div elements in the DOM

dojo.query("div#d2") //check for the existence of a div with id=d2

dojo.query(".blue") //returns a list of elements that have the blue class applied.

dojo.addClass("s1", "blue");  //add the blue class to the SPAN

dojo.query("span.blue") //returns only span elements with the blue class applied

While we could go on and on showcasing Base's easy-to-use API, let's save that for subsequent chapters and instead divert to a quick example of how easy it is to snap some dijits into your page without any additional programming.

Suppose you have the page shown in Example 1.4, “A very primitive form example”.

<html>
    <head>
        <title>Fun with Dijit!</title>
    </head>
        <body>
        Just Use the form below to sign-up for our great offers:<br /><br />
        <form id="registration_form">
            First Name: <input type="text" maxlength=25 name="first"/><br />
            Last Name: <input type="text" maxlength=25 name="last"/><br />
            Your Email: <input type="text" maxlength=25 name="email"/><br /><br />
            <button onclick="alert('Boo!')">Sign Up!</button>
        </form>
    </body>
</html>

Figure 1.5, “A functional but very ugly form” shows what that page looks like, although it's not very difficult to imagine.

Figure 1.5. A functional but very ugly form

That might have cut it back in '92, but it's wholly unacceptable for this day and age. Take a moment to consider what your normal routine would be at this point: define some classes, apply the classes, write some JavaScript to provide validation routines, etc.

To give you a taste of how the page would look after some Dojoification, take a look at Example 1.5, “A form that's not so primitive anymore (thanks to some Dojoification)”. Don't worry about what every little detail is doing; lots of pages follow on that get into the nooks and crannies of the finer details. For now, just familiarize yourself with the general structure of a page with some dijits snapped into it.

<html>
    <head>
        <title>Fun with Dijit!</title>

        <!-- Grab some style sheets for the built-in tundra theme that Dojo offers for
         styling the page, equipping you with a professional style without
any additional
         effort required. -->
        <link rel="stylesheet" type="text/css"
          href="http://o.aolcdn.com/dojo/1.1/dijit/themes/tundra/tundra.css" />
        <link rel="stylesheet" type="text/css"
          href="http://o.aolcdn.com/dojo/1.1/dojo/resources/dojo.css" />
        <!-- Add in some plain old CSS to line up the form elements more nicely -->

        <style type="text/css">
            h3 {
                margin : 10px;
            }
            label,input {
                display: block;
                float: left;
                margin-bottom: 5px;
             }
             label {
                text-align: right;
                width: 70px;
                padding-right: 20px;
             }
             br {
                clear: left;
             }
             .grouping {
                width:300px;
                border:solid 1px rgb(230,230,230);
                padding:5px;
                margin:10px;
             }
        </style>

        <!-- Load Base and specify that the page should be parsed for dijits after it
          loads -->
        <script
            type="text/javascript"
            src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js"
            djConfig="parseOnLoad: true" >
        </script>

        <!-- Load some dijits via dojo.require in the same manner that you
would #include
          some files in C programming or perform an import in Java -->
        <script type="text/javascript">
            dojo.require("dojo.parser");
            dojo.require("dijit.form.TextBox");
            dojo.require("dijit.form.ValidationTextBox");
            dojo.require("dijit.form.Button");
        </script>
    </head>

        <!-- Specify that the built-in tundra theme should be applied to
everything in the
          body of the page. (Dijit relies heavily on CSS so including the appropriate
          theme is crucial.)-->
        <body class="tundra">

            <h3>Sign-up for our great offers:</h3>

            <form id="registration_form">

                <!-- Weave some widgets into the page by supplying the tags and
including
                  a dojoType attribute so the parser can find them and swap
them out -->

                <div class="grouping">
                    <label>First Name:</label>
                    <input type="text"
                     maxlength=25
                     name="first"
                     dojoType="dijit.form.TextBox"
                     trim="true"
                     propercase="true"/><br>

                    <label>Last Name:</label>
                    <input type="text"
                     maxlength=25
                     name="last"
                     dojoType="dijit.form.TextBox"
                     trim="true"
                     propercase="true"/><br>

                    <label>Your Email:</label>
                    <input type="text"
                     maxlength=25
                     name="email"
                     dojoType="dijit.form.ValidationTextBox"
                     trim="true"
                     lowercase="true"
                     regExp="[a-z0-9._%+-]+@[a-z0-9-]+\.[a-z]{2,4}"
                     required="true"
                     invalidMessage="Please enter a valid e-mail address"/><br>

                    <button dojoType="dijit.form.Button"
                     onClick="alert('Boo!')">Sign Up!</button>
                </div>

            </form>
    </body>
</html>

And voilà, Figure 1.6, “A much better looking form, using out-of-the-box dijits” shows what it looks like, complete simple validation functionality.

Figure 1.6. A much better looking form, using out-of-the-box dijits

If you're intrigued by the examples in this chapter, and are ready to learn more about Dojo, then you've come to the right place. The following chapters systematically work through the specifics of the toolkit. But first, let's take a quick moment to reflect on what this chapter was all about (as we'll do in every chapter).