Menu

This tutorial is for Dojo 1.6 and may be out of date.

Up to date tutorials are available.

Hello Dojo!

Welcome! In this tutorial, we'll start from the ground up, with a simple HTML page. By the end of this tutorial, we'll have loaded Dojo into the page, as well as put some of the core functions to work. We'll touch on Dojo's modular structure, and discuss how to load dependencies into the page to make a richer experience.

Getting Started

Our starting point is a simple HTML page. We want to load Dojo into the page and add some code to signal our success.

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Tutorial: Hello Dojo!</title>
	<!-- load Dojo -->
	<script src="//ajax.googleapis.com/ajax/libs/dojo/1.6.3/dojo/dojo.xd.js"></script>
</head>
<body>
	<h1 id="greeting">Hello</h1>
</body>
</html>
View Demo

This is as vanilla as it gets. We've put the Dojo script tag into the <head> — it could also have gone at the end of the <body> — with a src attribute indicating the URL where the dojo.js file is located.

For this tutorial we are going to load the Dojo Toolkit via the Google CDN. If you have downloaded a Dojo release, adjust the URL to point to the location of dojo.js on your own server. Assuming the URL is correct, Dojo is now loaded quietly in the background. Next we need somewhere to put code that runs when Dojo is ready, so we can do something with it.

dojo.ready

Readiness, as it relates to an HTML page and the browser, can be a slippery moment to pin down. We need both the DOM to be ready for manipulation, and Dojo (and any indicated dependencies — more on that in a minute) to be loaded before any of our JavaScript code runs. Because ready has different meanings in different browsers, Dojo provides a reliable, cross-browser function for the purpose: dojo.ready. We pass it a function, and that function gets executed at the ready moment.

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Tutorial: Hello Dojo!</title>
	<!-- load Dojo -->
	<script src="//ajax.googleapis.com/ajax/libs/dojo/1.6.3/dojo/dojo.xd.js"></script>
	<script>
		dojo.ready(function(){
			alert("Dojo version " + dojo.version + " is loaded");
		});
	</script>
</head>
<body>
	<h1 id="greeting">Hello</h1>
</body>
</html>
View Demo

The function we pass to dojo.ready should cause an alert box to pop up when the page loads. Handily, Dojo has a version property that's useful for demos like this. As we get further into learning Dojo, the alert is going to get increasingly annoying, and we'll want to learn about logging to a browser console. But for now, we'll stay focused, and move on.

Loading Dojo is great, however it's more likely that you want to manipulate the page you just loaded Dojo into. We'll be digging into this in much more detail in other tutorials. For now, though, we'll simply get a reference to our <h1> and update its content.

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Tutorial: Hello Dojo!</title>
	<!-- load Dojo -->
	<script src="//ajax.googleapis.com/ajax/libs/dojo/1.6.3/dojo/dojo.xd.js"></script>
	<script>
		dojo.ready(function(){
			dojo.byId("greeting").innerHTML += ", from " + dojo.version;
		});
	</script>
</head>
<body>
	<h1 id="greeting">Hello</h1>
</body>
</html>
View Demo

This time, in our ready function, we use dojo.byId to retrieve the element in the DOM with the given ID, and append Dojo's version string to its innerHTML property.

Note that you can have as many calls to dojo.ready as you like, and each function will be executed in the order they were provided. In practice, if you have more than a few lines of code, it's common to define a named (non-anonymous) function and pass that to dojo.ready: 

function init() {
	alert("Dojo ready, version:" + dojo.version);
	// More initialization here
}
dojo.ready(init);

Note that when we pass in the function, we're passing it by name alone, without any parentheses after it.

If you came here for Dojo's Hello World, then we are long done. But earlier, we mentioned something about "indicated dependencies" — let's get back to that.

Modules

There's a bit more going on here than meets the eye. What does dojo.js actually get you? Dojo is a modular toolkit, with a package system that allows you to load only the code you need into your page and to make managing dependencies a lot easier. One of the perennial problems with JavaScript development has been the lack of a native package system for loading code (in the same way as you might require/import modules or classes with Java, PHP, Python etc.) Dojo fills that gap with an intuitive approach to code organization and a simple API (dojo.require) to indicate a dependency on a particular module.

What that means for now is that when we load dojo.js, we aren't loading the entire Dojo Toolkit, only the base modules. Our Dojo script tag loads a set of key functionality such as the package system, events, Ajax, DOM helpers, and other very commonly needed functionality.

Module loading for more shine

So, if setting innerHTML on that <h1> didn't quite make your day, let's add some shine. Dojo "base" includes the animation framework for visual effects and a couple of the more common effects (dojo.fadeOut and dojo.fadeIn). That's well and good, but we want the greeting to slide on to the page. For that we'll use dojo.fx.slideTo. The dojo.fx module is not already included in our dojo.js, so we'll need to load it:

// New: Require in the dojo.fx module
dojo.require("dojo.fx");

// Remember, dojo.ready waits for both the DOM and all dependencies
dojo.ready(function(){
	// The piece we had before - change our innerHTML
	dojo.byId("greeting").innerHTML += ", from " + dojo.version;

	// Now, slide the greeting
	dojo.fx.slideTo({
		top: 100,
		left: 200,
		node: dojo.byId("greeting")
	}).play();
});

The slideTo effect we want is a part of the dojo.fx module. The dojo.require line states the dependency, and asks the loader to load the file if it is not already available. There's no new script tag to fiddle with, and crucially, the rest of our initialization needn't change — we still use dojo.ready and our code will only run once the DOM is ready and all dependencies are loaded.

The next part is to put what we loaded to use. Like all property animations in Dojo, we pass in an object with a node reference, and any other properties to configure the animation. We'll be looking closer at animations in Dojo in a future tutorial.

View Demo

Conclusion

Getting started with the Dojo Toolkit is as simple as adding a script tag, but the broad scope of the toolkit is placed at your fingertips, as and when you need it. In this tutorial we've taken the first step towards putting Dojo to work in your web sites and applications. In future tutorials in this series we'll visit each of the major groups of functionality — from DOM helpers to Ajax, effects, events and more — exploring and explaining each step of the way.