First Steps

By on October 31, 2009 8:01 am

Note: The Dojo Quick Start Guide posts – while still relevant – are a bit dated. Please visit http://dojotoolkit.org/documentation/ 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:



    
    	Dojo Toolkit Test Page    
    
	
	
    
	
    
	    
    
    
        

Dojo Skeleton Page

Some Content To Replace


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:

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.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.");	
	};
	dojo.ready(init);
	
	// and/or pass an anonymous function
	dojo.ready(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.require("dijit.form.Button");
	dojo.require("dijit.TitlePane");
	dojo.ready(function(){
	    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.

Other posts in the series

Comments

  • Offer Ram

    I have just downloaded the DojoToolKit (Sunday 15.11.2009), And after extructing your package i can not find the “Test” folder anywhere.

    Please advice
    Thanks for your help
    Offer Ram

  • Kieran Kearney

    Same for me. No sign of any test folder.

    But I am looking forward to using the kit. I have read good reports about it.

    Kind regards,
    Kieran.

  • Sergi GB

    Hi Offer Ram and Kieran Kearney. You can find the tests if you download the file dojo-release-1.3.0-src.tar.gz instead of the file dojo-release-1.3.0.tar.gz.

    Hope it helps,

    Sergi GB

  • Hi, very helpful posts but why give code samples that include line numbers when copy/pasted?

    As an example, the wordpress.com code snippet feature has buttons for viewing/copying the source as plain text.

  • When tried the next code it did NOT work. Anyone can help?:

    dojo.require(“dijit.form.Button”);
    dojo.require(“dijit.TitlePane”);
    dojo.addOnLoad(function(){
    dojo.byId(“testHeading”).innerHTML = “We’re on our way!”;
    console.log(“onLoad fires after require() is done”);
    });

  • Amr Darwish

    It will be much appreciated to attach a complete html files that has a complete code after each step to ease follow up of this tutorial to save trainer time.

  • Amr Darwish

    I found the resolution of my last complaint of not working dojo code. Problem NOT in code but in the way I was loading dojo as follows:
    1- Next is the full path of dojo libs under my tomcat folder:
    C:\AppServer\Apache\Tomcat 6.0\webapps\js\dojotoolkit
    2- Next is the my test html that is used for dojo testing:
    C:\AppServer\Apache\Tomcat 6.0\webapps\DojoTest\dojo_test.html
    3- It is incorrect to use next to load dojo:

    4- Based on above env. the correct way to load dojo is:

    Note carefully the src attribute in both points 3 & 4 above.

    Conclusion: to get the most value of such tutorials it is highly appreciated to set a complete desc. env. as much as possible.

  • Amr Darwish

    missed on my prev comment:
    3- script attribute src=”js/dojotoolkit/dojo/dojo.js”
    4- script attribute src=”../js/dojotoolkit/dojo/dojo.js”

  • I’m trying to load the TitlePane widget and the Dijit button with the following code from the example:

    dojo.require(“dijit.form.Button”)
    dojo.require(“dijit.TitlePane”)

    But I get only the following error for the missing Button.js in Firefox (3.6.12) console:
    Could not load ‘dijit.form.Button’; last tried ‘../dijit/form/Button.js’
    [Break on this error] (function(){var _1=null;if((_1||(typeo…setTimeout(dojo._loadInit,100);}})();

    My dojo release is in the folder Dojo/dojo-release-1.5.0, the file from which I try to load this two modules is in Dojo/BasicDojo/basics/starting.html. I already tried to work with baseUrl option in djConfig, but it didn’t worked.

    Do you have any suggestions for this perhaps dumb problem, thanks for your time reading :)

  • Nevermind, I found the solution for this… hmm… dumb problem. I tried to use dojo local without any server in between. Now it’s working on a local server and the problem is solved.
    Thanks anyway…