First Steps

Note: The Dojo Quick Start Guide posts – while still relevant – are a bit dated. Please visit for expert tutorials and API documentation to help you get up and running with Dojo.

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

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" 
    	<title>Dojo Toolkit Test Page</title>    
	<!-- load the dojo toolkit base -->
	<script type="text/javascript" src="js/dojotoolkit/dojo/dojo.js"
	    djConfig="parseOnLoad:true, isDebug:true"></script>
	<script type="text/javascript">
	/* our JavaScript will go here */
	<style type="text/css">
	/* our CSS can go here */    
    <body><!-- this is a Typical WebPage starting point ... -->
        <h1 id="testHeading">Dojo Skeleton Page</h1>		
    	<div id="contentNode">
	    <p>Some Content To Replace</p>

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. Note that Dojo 1.6 will implement HTML5’s data attributes to pass HTML5 validation tests.

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:

<script type="text/javascript" src="js/dojotoolkit/dojo/dojo.js"
    djConfig="parseOnLoad:true, isDebug:true"></script>

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

<script type="text/javascript">
    var djConfig = {
<script type="text/javascript" src="js/dojotoolkit/dojo/dojo.js"></script>

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.ready (Note: this is an alias to dojo.addOnLoad. If you are using a version of Dojo prior to 1.4.0, you will need to use the more verbose name). Everything we do that could possibly affect the DOM should be started by passing dojo.ready a function:

// a very common method of loading code onLoad
	var init = function(){
	    console.log("I run after the page is ready.");	
	// and/or pass an anonymous function
	    console.log("I also run, but second. "); 

dojo.ready 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.

It’s important to note that you should not set on onLoad function directly on the tag when using dojo. dojo.ready(someFunc) is preferred over and window.onload = someFunc;

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:

	    dojo.byId("testHeading").innerHTML = "We're on our way!";
	    console.log("onLoad fires after require() is done"); 

Each “module” has its own dojo.require(), and knows not to load code it already has. Code executed by dojo.ready doesn’t run until after your dojo.require() statement have 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 if you downloaded the SDK or -src version.

Moving on

In the last example, we snuck a very common method into our dojo.ready 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.

Series Navigation« Getting the CodeDOM Magic »

Learn more about how SitePen can be your partner

SitePen is a strategic consultancy committed to achieving technical objectives, solving critical business problems and helping our customers build web applications the right way, the first time.