Getting Up and Running

The first part in this series will provide the most basic of overviews to Dojo, breeze through an installation, and provide a sample to test the installation. It is not intended to provide the deeper insights into toolkit that the Dojo site's own documentation provides nor a troubleshooting resource for installations; it's just meant to whet your appetite.
That said, in most cases, the directions that follow should suffice to get an installation up and running as it is not a complicated process.

Table of Contents
A Quick Overview Installation Basics Code Basics Core Dojo library djConfig Attributes Dojo CSS files Dojo packages Simple Code Example Other Sources
Assets
Sample Code

A Quick Overview

Dojo, or the Dojo toolkit, is a set of JavaScript APIs that provides advanced user interface controls (trees, data driven dropdown selects, etc.), data packaging classes, AJaX tools and more.

These APIs are highly modular and broken into individual files so that they can be individually loaded (using Dojo specific directives) so as to keep the page weight light. These files must be published from the Web server in a public directory as they are aggregated on the client side.

Most of the control initialization and data exchange within the Dojo toolkit is done through JSON.

Typically Dojo does its work by parsing the Web page, once it is loaded in the browser. The Dojo parser looks for special attributes, such as dojoType, attached to HTML tags like <div>s and other HTML form tags. It will use these HTML DOM nodes as the root of the controls it generates programmatically.

Installation Basics

Download the toolkit from the Dojo site. Current distributions are packaged as a GZip'd tar or Windows-friendly Zip file which can initially be unpacked to the local hard drive. The following subdirectories (which represent the base packages for the Dojo JavaScript classes) will need to be transfered to a base directory that is publically accessible to the Web:

• dijit
• dojo
• dojox
• util

Since the Dojo toolkit is a version controlled distribution, it would be good to add these 4 subdirectories to a parent directory that reflects a version number. A suggestion, that is commonly employed by other Dojo installations would look like this:

• [public Web directory]/dojo/[version]/

Where [public Web directory] is the publically accessible Web directory, and [version] is specific Dojo version contained in that directory. Subsequent versions would site at peer level in the /dojo/ subdirectory. So for example, if you installed Dojo version 1.1.0 (the current version as of this writing) on a Windows box into the stand-alone ColdFusion Server's wwwroot in a scripts subdirectory, the path would be:

• /scripts/dojo/1.1.0/

And when Dojo 1.2 is release you could install it side by side to:

• /scripts/dojo/1.2/

Code Basics

To Dojo-enable a page three things are needed:

• the inclusion of the core Dojo JavaScript library
• the inclusion of some Dojo CSS files
• a JavaScript block that includes the various needed Dojo packages

Core Dojo library

The basic Dojo functionality is contained in the dojo.js file which must be included before all the other Dojo JavaScript files and must preceed module inclusion. This is usually done with a normal HTML script tag. What is of genuine importance here is the djConfig attribute. This is a special Dojo-specific attribute that drives the way that the Dojo parser handles content.

example snippet

djConfig Attributes

There are a number of useful configuration attributes that can be passed to the parser that might help you during development.

Attribute	Values	Description
parseOnLoad	true / false	Parse the page for Dojo content immediately. While it seem that you should always do this, there are times when it's important to delay. For the everyday though, just set it to "true"
usePlainJson	true / false	Makes Dojo a less strict when reading in JSON content.
isDebug	true / false	When set Dojo will push content to Firebug. If Firebug is not available it will force Dojo to pull in (and display) the version of Firebug Lite distributed with Dojo.
debugAtAllCosts	true / false	When set Dojo will generate even more debugging information (it should be said: do not leave this enabled in a production environment) This is also helpful when using Internet Explorer.

Dojo CSS files

The Dojo toolkit offers some thematic elements that are handled largely via CSS files. A list of the stock themes available with the Dojo toolkit can be observed as subdirectories at the following location:

• [public Web directory]/dojo/[version]/dijit/themes/

Where [public Web directory] is the installation directory for Dojo and [version] is the version-specific subdirectory (as noted above in the Basic Installation section).
As of version 1.1.0 there are the following themes available:

• a11y
• nihilo
• soria
• tundra

Some of the themes are more complete than others and some have special purposes (a11y for example is aimed at accessibility). There are other themes available in the Dojo SVN repository and through 3rd parties. As well, there is some adequate documentation on creating themes available on the 'net.

example snippet

Dojo packages

The Dojo toolkit breaks up each package module into separate files. While the development effort for the Dojo team to manage all the additional files increases the amount of effort required to manage the project, it is crucial to maintaining a light-weight download for Dojo-enabled pages.
While there is little you can do without including at least a few different Dojo modules, there is actually only one module that must be included, that being the dojo.parser module.

example snippet

Simple Code Example

buttonsample.html

Other Sources

While this article will get you up and running, it is hardly a definitive work. While there are a fair number of beginning guides for general purpose Dojo development, two of the better ones being:

• SitePen's Dojo Quick Start Guide
• Dojo's own Book of Dojo

I would strongly recommend that you read one or more of the quick start offerings before continuing on in this series. I make no attempt to fill in the gaps for the newcomer beyond this point.