Start by making a skeleton HTML file for use as a basic template for any example:

This page has a DOCTYPE of “HTML/4.01 Strict”, and almost passes W3C validation. This can be fixed, but the shorthand is convenient. You will learn about both valid and convenient methods in this guide.

Configuring Dojo

Dojo has a mechanism for setting various configuration options at runtime. The two most common are parseOnLoad, which toggles page-load parsing of widgets and in-markup code, and isDebug, which enables or disables certain debugging messages.

Conveniently, you can set these options directly in the tag that loads in dojo.js via a custom attribute named djConfig. Simply modify the skeleton HTML template to add the new attribute:

If the above validation concerns you (you know who you are), you can setup a global djConfig variable before dojo.js is loaded:

Both examples have the same effect.

When can I start?

As soon as the document is ready and loaded…

There are a number of cross-browser differences in defining “ready”, so to aid in your continued sanity, Dojo has a method of executing code when the document is really “ready”: dojo.addOnLoad. Everything we do that could possibly affect the DOM should be started by passing dojo.addOnLoad a function:

dojo.addOnLoad is a fundamental aspect of using Dojo, and is very important to remember. Without it, you cannot be sure all the necessary content has been loaded before your own code begins to execute.

More than just dojo

Dojo has a package system built in to load all the code you need, controlled by dojo.require(). This function allows us to pull in parts of the Dojo Toolkit not provided for in the Base dojo.js, such as Drag and Drop, additional animations, dijit widgets, dojox projects, or even your own code.

For example, to load the code needed to use the TitlePane widget, and a Dijit Button into your page include the modules dijit.TitlePane and dijit.form.Button:

Each “module” has it’s own dojo.require()’s, and knows not to load code it already has. Code executed by dojo.addOnLoad doesn’t run until after your dojo.require()’s are all finished loading, making it that much safer and convenient to use.

A full list of available widgets and the module they live in can be found at the Dijit API pages, or explored by browsing the dijit/tests/ folder that came with your download.

Moving on

In the last example, we snuck a very common method into our addOnLoad code: dojo.byId(). This returns the domNode of an element by its id attribute. dojo.byId() is a convenient way to access a specific node, and manipulate it. Here we’re changing the text of the heading in the body, through its .innerHTML property.

If all you see is “We’re on our way”, you really are on your way to some really interesting web development: dojo.bliss. If you are experiencing errors, something has gone wrong. A lot of common mistakes are covered in the FAQ, available at the Dojo Toolkit website.