Dojo: The Definitive Guide

Prepping for Development

You don't need any fancy tools nor do you have to be able to configure a beast of a web server like Apache to learn how to develop with Dojo. In fact, very few examples in this entire book require you to interact with a web server at all. Most resources will be resolved via relative paths on your local machine or they will be cross-domain loaded, so for the most part, it's just you, your favorite text editor, and your web browser.

There are three primary ways you can download Dojo and prep for development: downloading an official release, checking out the latest and greatest from Subversion, and using a cross-domain (XDomain) build that's available from AOL's Content Developer Network (CDN). Let's walk through each of these options. Although downloading an official release to your local machine may be the most typical approach, there can be specific value in the other approaches as well.

Getting Dojo

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.

Downloading an official release

Downloading the latest official Dojo release is by far the most traditional way to prep for development. An "official" release is really nothing more than a tagged, blessed snapshot from the Subversion repository that has been well-tested and that comes with some helpful release notes. You can find official releases of the toolkit at http://dojotoolkit.org/downloads; the only notable caveat when downloading an official release is that it does not come packaged with the build tools. To retrieve the build tools, you either need to use Subversion or download a source release, which you can find at http://download.dojotoolkit.org/.

When you uncompress the downloaded archive, you'll find it expands into a folder that has the general form dojo-release-x.y.z, where, "x," "y," and "z" correspond to the major, minor, and patch numbers for a particular release. To keep your setup and URLs as generic as possible, you may want to rename the folder in place so that it is simply called js (short for JavaScript). Other options include using server directives to alias dojo-release-x.y.z to js, or using symbolic links on Linux and Unix environments. In any case, this extra effort has the advantage of allowing you to use a relative path such as www/js to point to Dojo instead of a more brittle path such as www/dojo-release-x.y.z.

Tip

Creating a symbolic link is easy. On Linux, Mac OS X, or Unix platforms, simply execute a command of the following form from a terminal: ln -s dojo-release-x.y.z js. You can read more about symbolic links by reading the man page via the man ls command.

Once you have downloaded Dojo, you might initially be surprised that it's all not in one JavaScript file, but don't worry. A quick look at what unpacks reveals that the code base is broken into the same architectural components that we just talked about in the previous section—Base (dojo/dojo.js ), Core (dojo ), Dijit (dijit ), DojoX (dojox), and Util (util). While we'll systematically work through all of this, the only action that's required to get Base into your page is to provide the relative path to the dojo.js file (located at dojo/dojo.js via a SCRIPT tag in your page just like any other JavaScript file). Easy as pie.

Downloading from Subversion

The latest official build is probably what you want to use for development. Still, if you're interested in maintaining a copy of the Subversion repository to stay up to date with the bleeding edge, then read this section closely; it walks you through the steps involved in checking out Dojo from Subversion and getting a convenient development environment set up. Developing against the Subversion trunk might be helpful if you want to keep a close eye on a bug that's being fixed, if you want to try out a new feature that's in the works, or if you're a first-class hacker who just can't rest easy unless you're always in the know with the latest.

Tip

For the authoritative reference on Subversion, take a look at Version Control with Subversion, which is available at http://svnbook.red-bean.com/.

Dojo's Subversion repository is located at http://svn.dojotoolkit.org/src/, so start there if you're interested in skimming some code in your web browser. You'll want to check out the code from the externals view that can be accessed at http://svn.dojotoolkit.org/src/view/anon/all/trunk, however, which keeps things simple by grabbing the entire toolkit in one fell swoop.

Tip

The Subversion externals property provides a way of constructing a working copy that would normally require multiple separate checkouts. You can read more about it at http://svnbook.red-bean.com/en/1.0/ch07s03.html.

In order to check out the code, execute the following command from a terminal. (The remainder of this section assumes you've performed the checkout from inside of a folder named www.)

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

Just as if you had downloaded an official release, you'll have an svn folder that contains subfolders corresponding to each major component of the toolkit (dojo, dijit, dojox, and util ) when your Subversion checkout completes. However, your util folder will contain the build scripts (and possibly a few other things auxiliary tools used to support the toolkit). We'll delay elaboration on Subversion details, but do note that it is not difficult to have multiple versions of Dojo around—say, the latest official release, a nightly build, and an actual checkout of the repository—and use a server directive or other means of toggling between them all, depending on which version you'd like to use at any given time.

AOL's CDN

AOL hosts a cross-domain version of Dojo on their Content Delivery Network (AOL CDN) and makes it available for you to use by simply providing a few configuration parameters and including a SCRIPT tag that points to the XDomain build of Dojo on AOL's CDN server. Because it's just that easy, all of the examples in this book use the XDomain build so there is minimal fuss when you are trying things out.

As alluded to in the previous two sections, you normally load Dojo by pointing to your own dojo.js file; specify a relative path like this one:

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

Using AOL's XDomain build is just as easy: simply change the src reference and let Dojo (and AOL) take care of the rest. The following SCRIPT tag illustrates this process for Dojo 1.1:

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

The dojo.xd.js was emphasized in the code because if you accidentally specify dojo.js, you'll probably get an error instead of the Dojo goodness you were looking for. It is also noteworthy that the 1.1 in the src path references the latest bug release for the said version. You could request a specific bug fix release by asking for, say, 1.1.0 or 1.1.1. You may want to bookmark http://dev.aol.com/dojo because it's the ultimate authority on what versions of Dojo are available via the CDN.

Debugging with Firebug

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.

Tip

Firebug is an amazing tool that's hard to live without once you've experienced it. You can save yourself a lot of time if you develop in Firefox and use Firebug for all that it's worth. However, it's best to frequently test in IE (say, at least every 30 minutes) to catch any hard-to-find anomalies that might creep into your application. For example, if you leave a trailing comma after the last key/value pair in a JavaScript associative array, Firefox forgives you, but IE does not . . . and the error message you get back from IE isn't very helpful either.

By far the most common function you'll probably use from Firebug is console.log, which allows you to print information to the Firebug console from inside of your JavaScript. (We're all tired of alert boxes by now, right?)

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 contains a Firebug tutorial that you may find helpful for development.

Browser Security Settings for Running Dojo Locally

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:

1. In the address bar, type about:config and press the Enter key.

2. Change the value of security.fileuri.origin_policy to 3 or greater.

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

Lightweight Server Responses

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.

Tip

All of the (very few) examples involving the need to serve up some dynamic content or explicitly get a response for the server require nothing more than a single command in a terminal, so don't be scared away—these server-side examples are for the faint of heart! Of course, you are more than welcome to skip any examples involving server-side technologies completely; a thorough discussion of what is happening will always accompany them.

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 locates it and makes it available for use.

Example 1-1. A very simple CherryPy application

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, 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.