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.
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 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.
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 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.
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.
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:
In the address bar, type
about:configand press the Enter key.Change the value of
security.fileuri.origin_policyto3or greater.
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.
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.
Get Dojo: The Definitive Guide now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
