Documentation
Hello Dojo!
Welcome to Dojo! In this tutorial, you’ll learn how to load Dojo and begin exploring some of its core functionality. You’ll also learn about Dojo’s AMD-based module architecture, discover how to load additional modules to add extra functionality to your Web site or application, and find out how to get help when things go wrong.
- Difficulty: Beginner
- Dojo Version: 1.7
Getting Started
Our starting point is a simple HTML page that includes dojo.js from the Google CDN, and not much else:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Tutorial: Hello Dojo!</title> <!-- load Dojo --> <script src="//ajax.googleapis.com/ajax/libs/dojo/1.7.2/dojo/dojo.js" data-dojo-config="async: true"></script> </head> <body> <h1 id="greeting">Hello</h1> </body> </html>View Demo
This code makes the Dojo loader available for use by the rest of the page. One thing you’ll probably notice immediately as a new user of Dojo 1.7 is the data-dojo-config attribute. This special HTML5 attribute is used to configure Dojo when it is loaded and contains of a list of properties that looks and works just like a JavaScript object literal but without the opening and closing curly brackets.
The CDN version of Dojo does not include all of the debugging capabilities of the SDK version of Dojo. For development, it’s highly recommended that you download and use the SDK instead.
In contrast to earlier versions of Dojo, which automatically load everything in Dojo Base by default, setting async: true causes Dojo 1.7 to switch into “baseless” mode (also known as “async mode” or “AMD mode”, in contrast to the old loader mode from Dojo 1.6 and earlier which is known as “sync mode” or “legacy mode”). In this mode, modules like fx, xhr, and query aren’t loaded automatically. In fact, in this mode, the only thing that gets loaded automatically is the module loader itself. This enables you to truly require only what you need, making code written with Dojo 1.7 smaller and faster than code written with other, more monolithic libraries.
All tutorials in the Dojo 1.7 tutorial series use baseless Dojo, preaching that loading only what you need makes for better, lighter Web applications.
In addition to eliminating the overhead of Dojo Base, enabling async mode replaces the slower, synchronous dojo.require-based module loader with a new AMD loader. This new loader is significantly faster than the old loader and follows the AMD standard, which means any non-Dojo code written with AMD syntax can be loaded and used just as easily as a native Dojo module!
You can learn more about configuring the loader in the Configuring Dojo with dojoConfig tutorial.
Defining and requiring modules
Modules in Dojo 1.7 are identified by a string that closely resembles a file path. For example, “my/module/id” is a Dojo 1.7 module identifier. In fact, these identifiers are used to map directly to JavaScript files, which means that a request to load the module “my/module/id” will cause the loader to load whatever module is defined in my/module/id.js. (There are more complex ways of mapping modules to files, but this is all you need for most use cases.)
In order to actually require and define modules for use, two global functions are provided by the loader: require, which is used to load one or more modules, and define, which is used to define a module. Both of these functions take two arguments: a list of module IDs that must be loaded, and a callback function that is executed once those dependencies have been loaded. This is usually easier to understand by example; a typical module definition will look like this:
// In demo/myModule.js (which means this code defines
// the "demo/myModule" module):
define([
// The dojo/dom module is required by this module, so it goes
// in this list of dependencies.
"dojo/dom"
], function(dom){
// Once all modules in the dependency list have loaded, this
// function is called to define the demo/myModule module.
//
// The dojo/dom module is passed as the first argument to this
// function; additional modules in the dependency list would be
// passed in as subsequent arguments.
var oldText = {};
// This returned object becomes the defined value of this module
return {
setText: function(id, text){
var node = dom.byId(id);
oldText[id] = node.innerHTML;
node.innerHTML = text;
},
restoreText: function(id){
var node = dom.byId(id);
node.innerHTML = oldText[id];
delete oldText[id];
}
};
});
This demo module has a single dependency of its own (on dojo/dom) and its value is defined as an object with two methods, setText and restoreText. Now that we’ve defined this module, we can load and use it in some actual code:
// Require the module we just created
require(["demo/myModule"], function(myModule){
// Use our module to change the text in the greeting
myModule.setText("greeting", "Hello Dojo!");
// After a few seconds, restore the text to its original state
setTimeout(function(){
myModule.restoreText("greeting");
}, 3000);
});
View Demo
Using our custom module, this code simply replaces the content of the <h1 id="greeting"> element with “Hello Dojo!”, then restores its original content three seconds later. Note that we aren’t requiring all sub-dependencies in this require call: the loader will automatically load any necessary sub-dependencies until all required code has been loaded.
To learn more about defining and requiring modules in Dojo 1.7, check out the Defining Modules tutorial.
It is possible to load AMD modules using dojo.require when running in legacy mode, and it’s possible to load legacy modules when running in async mode using the dojo/require! plugin. This makes it possible for existing applications to transition over time to the new loader & module format.
Waiting for the DOM
Most JavaScript libraries include a function that allows you to execute code after the DOM has loaded, but before all external media (such as images) have loaded, and Dojo is no exception. In Dojo 1.7, this is accomplished using a special kind of module called a plugin. Plugins can be required like any other module, but their special functionality is only activated by adding an exclamation point to the end of the module identifier. In the case of the DOM ready event, Dojo provides the dojo/domReady plugin. Simply include this plugin as a dependency in any require or define call and the callback will not be fired until the DOM is ready:
require(["dojo/dom", "dojo/domReady!"], function(dom){
var greeting = dom.byId("greeting");
greeting.innerHTML += " from Dojo!";
});
View Demo
The example above simply adds some text to the greeting element—something that can only be done reliably once the DOM is loaded. Again, note that the module identifier ends with !; without this, the dojo/domReady module would simply be required like any other module and passed as an argument to the callback.
More information on DOM manipulation functions can be found in the Dojo DOM Functions tutorial.
Adding visual effects
If setting innerHTML on that <h1> didn’t quite make your day, let’s liven it up by adding some animations. One module we can load to add effects to the page is dojo/fx. Let’s add a sweet sliding animation to the greeting with dojo/fx’s slideTo method:
require(["dojo/dom", "dojo/fx", "dojo/domReady!"], function(dom, fx){
// The piece we had before…
var greeting = dom.byId("greeting");
greeting.innerHTML += " from Dojo!";
// …but now, with a fun animation!
fx.slideTo({
top: 100,
left: 200,
node: greeting
}).play();
});
View Demo
As you can see, we’ve added one more dependency on dojo/fx, then used that module to play an animation on our greeting element.
More information on effects and animations can be found in the Dojo Effects and Animations tutorials.
Getting Help
Whenever you get confused or run into a tricky problem, you’re not alone! Volunteers are ready to assist via email on the dojo-interest mailing list and via IRC at #dojo on irc.freenode.net. If you think you’ve found an error in our documentation, or read something that’s misleading or confusing, the feedback links at the bottom of all documentation pages can be used to let us know.
If you need urgent or confidential help, or have a problem that can’t be solved by our team of volunteers, commercial Dojo support and training workshops are also available through SitePen.
Where to next?
Getting started with the Dojo Toolkit is as simple as adding a script tag and requiring some modules, but the immense scope and power of Dojo means we’ve barely scratched the surface of what it can do. Depending upon your needs, there are a few different paths through this tutorial series:
- If you’re interested in adding some features and effects to an existing static Web page or server-driven Web site, you’ll want to look next at Using dojo/query, Events with Dojo, and the effects and animations tutorials.
- If you want to add some Ajax to your site, Ajax with Dojo is your ticket.
- If you’re looking to integrate a rich widget library with your Web site or application, take a look at our tutorial series on Dijit widgets.
- If you’re trying to learn more about architecting complex Web applications and leveraging the power of Dojo’s utility functions, head over to the Core Concepts section.
- If your goal is a mobile application, get up and running with Getting Started with dojox/mobile.
No matter your desired outcome, Dojo provides industry-leading open-source tools that can help you get your project done in less time with amazing results. We look forward to seeing what you come up with!
About the Author
Colin Snover is a Dojo committer and the least camera shy software engineer at SitePen, Inc.
Tutorial Created By
