Dijit: Prepackaged

By on November 5, 2009 2:00 pm

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 Test Page    
    
	
    
	
	

	
    
    
    
	

Dijit Skeleton Page

Claro was added to Dojo at version 1.5. If you are using Dojo prior to version 1.5, replace all instances of claro with tundra.

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:

The dijit.Dialog is a modal dialog box. It takes the node’s content, and displays it front-and-center on the viewport, awaiting user interaction. It can also act as a form element. To explore beyond this guide, visit the 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.

If 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(); });

Other posts in the series