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.
Dojo’s widget system is called Dijit. Dijits are the official, accessible, themed components shipped with the Dojo Toolkit. It has its own namespace, and likewise its own collection of utility functions:
dijit.byId("firstWidget"); // is a reference to the actual widget.
dijit.byId("firstWidget").domNode; // is the domNode the widget uses
// as opposed to:
dojo.byId("testHeading"); // is a domNode in our page
Using Dijits
There are two ways to make Dijits: via markup, or programatically. As of Dojo 1.6, the markup supports HTML5 data attributes to support validation against the HTML5 validator.
Start by making a new HTML skeleton file. We’ll make a couple of changes for Dijit styling: add the default theme claro‘s CSS, and set <body class="claro"> to enable it:
Dijit Skeleton Page
Dijit uses Dojo’s package system to track dependencies via dojo.require. Simply call in the modules you need in a script tag. For instance, to use a dijit.Dialog and dijit.form.Button, you need the following calls:
dijit.Dialog API Pages, or the reference guide.From markup
You can specify all the attributes needed to setup your widget directly in markup, the most important being the dojoType. The Dojo parser finds the dojoType attribute, and turns the node into a Dijit with the matching classname. title is a common attribute used by many widgets with headings:
I am the Content inside the dialog.
If parseOnLoad is true, the widgets will be created, then dojo.ready code will be executed. If you want to execute code before widgets are parsed, set parseOnLoad:false, and put your code inside a dojo.ready function as before. Issuing the command dojo.parser.parse(); will create the widgets when you are ready.
parseOnLoad is true, the parser is loaded automatically. Otherwise, you must issue a dojo.require("dojo.parser"); call to include the required functions. All Dijits use the parser, so it is included automatically.From JavaScript
The same results can be achieved using valid HTML and JavaScript. Our markup is simple, valid HTML:
I am the Content inside the dialog.
And our script is standard Dojo code. We pass all the attributes as an object into our constructor, and tell it to use the node “sampleNode” for its content. All Dijits (or declared classes) can be created using the JavaScript new function.
dojo.require("dijit.Dialog");
dojo.require("dijit.form.Button");
dojo.ready(function(){
// make the button
var theButton = new dijit.form.Button({
onClick:function(){
console.log("clicked");
}
},"myButton");
// make our Dialog
var theDijit = new dijit.Dialog({
title:"The First Widget"
},"sampleNode");
// make sure its started. parser does this if using markup
theDijit.startup();
});
When the button is clicked, you should see the word “clicked” in your Firebug (or Firebug Lite) console.
Manipulating The Widget
With our dialog successfully loaded and parsed (no errors were thrown, and the content of the Dialog is hidden), we need to explore some of the ways to manipulate the widgets. The function dijit.byId gives us a reference to our widget. The dijit.Dialog has an id of sampleNode.
To make the button the button control the dialog, modify the button’s onClick attribute to do more than print text:
I am the Content inside the dialog.
If using the programmatic method, modify the lines that create the button:
// make the button
var theButton = new dijit.form.Button({
onClick:function(){
dijit.byId("sampleNode").show();
}
},"myButton");
The dijit.Dialog inherits from a dijit.layout.ContentPane which provides a few content-handling methods, including setHref. Add a new button outside the dialog with a new onClick function:
I am the Content inside the dialog.
Or programatically by adding another button to our HTML:
I am the Content inside the dialog.
And an additional new call:
// make the button
var theButton = new dijit.form.Button({
onClick:function(){
dijit.byId("sampleNode").show();
}
},"myButton");
var theButton = new dijit.form.Button({
onClick:function(){
dijit.byId("sampleNode").setHref("sample.txt");
}
},"otherButton")
Adding an id attribute to the paragraph inside the Dialog is an easy way to demonstrate another useful Dijit tool, dijit.getEnclosingWidget, to find which widget contains a passed domNode:
// show the dialog onLoad, without knowing it's id
dojo.addOnLoad(function(){
// add
to the dialog content
var p = dojo.byId("myPara");
var theDijit = dijit.getEnclosingWidget(p);
theDijit.show();
});
dojo.getEnclosingWidget -> dijit.getEnclosingWidget
Got a console warning with dojo-1.4.0:
DEPRECATED: dijit.layout.ContentPane.setHref() is deprecated. Use attr(‘href’, …) instead. — will be removed in version: 2.0
s|setHref(“sample.txt”)|attr(“href”, “sample.txt”)|