This entry is part 1 of 4 in the series Dive Into Dojo
Notice: There is a newer version of this post available: Dive into Dijit with AMD

One huge feature that sets the Dojo Toolkit apart from other JavaScript libraries is its UI component system: Dijit. A flexible, comprehensive collection of Dojo classes (complemented by corresponding assets like images, CSS files, etc.), Dijit allows you to create flexible, extensible, stylish widgets. To learn how to install, configure, and use basic Dijits within your web application, keep reading!

Dijit Widgets

Requiring Proper Classes and Assets

Since Dijit includes a collection of UI components, it comes bundled with four supported themes: nihilo, soria, tundra, and (as of Dojo 1.5) claro. Each theme contains images and CSS files to control the overall display of the widgets. CSS files must be explicitly included into each HTML page:


You can view each theme set using the Dijit Theme Tester. You may also define your own theme.

There is another consideration that must be made when Dojo is included in the page: parseOnLoad. Adding parseOnLoad to the djConfig attribute will direct Dojo to scour the page for elements that should become Dijit widgets and make them such:


This parseOnLoad setting must be true if you prefer automatically instantiating Dijits defined declaratively (which we’ll examine below). You will also need to require Dijit classes you plan to use within the page. For example, If you want the dijit.form.Button widget within your pages, you’ll need to require that class:

dojo.require('dijit.form.Button');

In the body tag of your page, or in a parent node of your widgets, you need to define the class name based upon the theme you would like to use.

<body class="claro">

Now let’s learn the two ways you can create Dijit widgets.

Two Ways to Play

One of the most notable features of the Dijit system is that you may create a Dijit widget in one of two ways: declaratively (using HTML markup and custom attributes) or programmatically (using raw JavaScript, mostly likely within a dojo.ready block). Let’s take a look at how we can make a basic SELECT element an Dojo-enhanced widget.

The Basic SELECT Element

<select name="players" id="players">
	<option value="">Select an Arsenal Player</option>
	<option value="Arshavin" selected="selected">Andrey Arshavin</option>
	<option value="Vermaelen">Thomas Vermaelen</option>
	<!-- more OPTION elements here -->
</select>

This is a static SELECT element containing a series of OPTION elements. We know we’d like for this SELECT element to become a dijit.form.FilteringSelect widget so we must require this class:

dojo.require('dijit.form.FilteringSelect');

Now that the dijit.form.FilteringSelect class is available, we can use the declarative or programmatic method of enhancing our SELECT element.

Declarative Method

The declarative method of enhancing the SELECT element is done within the HTML element itself:

<select name="players" id="players" dojoType="dijit.form.FilteringSelect" autoComplete="true" pageSize="10">
	<option value="">Select an Arsenal Player</option>
	<option value="Arshavin" selected="selected">Andrey Arshavin</option>
	<option value="Vermaelen">Thomas Vermaelen</option>
	<!-- more OPTION elements here -->
</select>

This declarative example illustrates the use of the dojoType attribute which identifies which Dijit the given element should become. Since we have declared parseOnLoad “true” in our djConfig, Dojo will find this element immediately upon load (due to the element having a dojoType attribute) and instantiate and initialize the widget.

Options of the dijit.form.FilteringSelect class are also custom attributes. This widget will autocomplete when the user types a value and page every 10 items. Just as with a normal SELECT element, “Arshavin” will be selected initially.

Programmatic Method

The programmatic method of enhancing the SELECT element is done completely with JavaScript:

//require the class
dojo.require('dijit.form.FilteringSelect');

//when the class has been loaded...
dojo.ready(function() {

	//dijitize my SELECT!
	var enhancedSelect = new dijit.Form.FilteringSelect({
		autoComplete: true,
		pageSize: 10
	},'players');

	//dijitize any form field individually
	var inputDijit = new dijit.form.Textbox({/*options*/},'myInput');
	var textareaDijit = new dijit.form.Textarea({/*options*/},'myTextarea');
	var mySelectDijit = new dijit.form.FilteringSelect({/*options*/},'mySelect');
	var dateDijit = new dijit.form.DateTextBox({/*options*/},'myDate');
	var timeDijit = new dijit.form.TimeTextBox({/*options*/},'myTime');
	var checkboxDijit = new dijit.form.CheckBox({/*options*/},'myCheckbox');
	var radioDijit1 = new dijit.form.RadioButton({/*options*/},'myRadio1');
	var radioDijit2 = new dijit.form.RadioButton({/*options*/},'myRadio2');

});

Reminder:  the programmatic method of Dijit creation does not require you to enable parseOnLoad within the djConfig settings.

Since you may have a large form and may not have the desire to target individual elements for Dijitization, you may want to use dojo.behavior to create Dijits by selector:

//require the class
dojo.require('dojo.behavior');
//when it has loaded...
dojo.ready(function(){
	//add two behaviors:
	dojo.behavior.add({
		//find SELECT elements, make them a FilteringSelect Dijit
		'select': {
			found: function(item) {
				new dijit.form.FilteringSelect({/*options*/},item);
			}
		},
		//find all radio buttons, make them dijit.form.RadioButton Dijits
		'input[type="radio"]': {
			found: function(item) {
				new dijit.form.RadioButton({  },item);
			}
		}/* ,
			more selector => Dijit creation....
		*/
	});
});

You could also run a few dojo.query searches for elements and loop through them to create new widgets, but the dojo.behavior method provides a cleaner syntax.

Dijit Form Controls
A Dijitized form; easily customizable and themeable.

Accessing Dijit Widgets and Widget Properties

Accessing a specific DOM element can be easily accomplished by using Dojo’s byId method. Dijit features its own byId method which retrieves the Dijit widget registered within the widget system with the ID specified. If the element to be made a Dijit has an ID, the widget ID will be that same value. If the source element doesn’t have an ID attribute, a widget ID will be generated. If we wanted to retrieve the widget object for the declaratively created “players” Dijit above, we would code:

//grab the players dijit.form.Filtering widget
var enhancedSelect = dijit.byId('players');

Dijit Form

View a listing of all properties and methods of a Dijit using dijit.byId within Firebug.

If we wanted to access the pageSize for which the Dijit widget was created from, we would code:

var pageSize = dijit.byId('players').get('pageSize'); // returns 10

If we wanted to change the pageSize for the widget, we would code:

dijit.byId('players').set('pageSize',20); //now pageSize is 20

Note: Dojo 1.5 introduces “get” and “set” methods to handle property values. In Dojo 1.4 and earlier, you would use “attr” in place of both get and set in the previous example.

Listening to Widget Events

Dijit widgets use Dojo’s native connect method to listen to events on the given widget:

dojo.connect(dijit.byId('player'),'onChange',function() {

	//the user has selected a new item
	//do something

});

Each widget supports a select number of events so be sure to view the documentation for the widget to ensure the event you’d like to listen to is supported.

The Dijit Collection

Dijit is also an incredible UI library that has the potential to enhance your website and save you an immense amount of time in doing so. Dijit includes a large number of solid widgets including:

  • Context, popup, and dropdown menus
  • Form element replacements like buttons, combo boxes, checkboxes, radio buttons, and text boxes
  • Date and time selection widgets
  • WYSIWYG Editors
  • Horizontal and Vertical Sliders
  • Progress Bars
  • Tabs and Accordions
  • Tree Structures (including Drag and Drop)
  • Dialogs and Tooltips
  • Layout widgets with slide controls and splitters

And if Dijit doesn’t have a widget you want, there’s a good chance it’s available in DojoX (Dojo Extensions)! To see many of these widgets in action, visit the Dojo Theme Tester.

Dijit Resources

The following resources will help to aid your Dijit education:

Stay tuned for more in-depth Dijit posts in the future. This amazing library contains a vast array of useful widgets to enhance your website!