Dijit Basics

This page lists general info about how to use dijit. The info for individual widgets is on separate pages.

Supported Features

Supported browsers

IE6+
FF2.0
Safari 3

We're dropping support Konqueror because it doesn't have a big enough install base to warrant our time supporting (coding and testing) it, nor do we want to increase code size/complexity in order to support it.

Opera won't be supported either, at least not for the 0.9 release.

A11Y

For Release 1.0 all core widgets will:

render in High Contrast mode. High contrast mode is detected on IE and FF and an additional a11y style class is added which provides text equivalents for items implemented using css background images.
be usable with images turned off
be keyboard accessible in IE 6+ and Firefox 2+ on Windows.
implement Accessible Rich Internet Applications (ARIA) specifications

Exceptions

All drag and drop operations may not be fully keyboard accessible - this is a stretch goal. To meet accessibility requirements, applications using drag and drop features must provide an alternate, keyboard accessible mechanism to perform the same functionality.
Many widgets will not function properly if CSS is turned off due to the heavy reliance on CSS positioning.

I18N

Internationalization support mainly refers to boilerplate text in widgets, such as error messages like "value out of range". It also refers to date formatting / parsing, which is different in different countries.

Documentation

All widgets will be documented both API doc and manual.

Protocols

http:// and https:// (should run without security warnings). file:// doesn't need to work.

Styling

There's a certain baseline for A11Y support (see the accessibility section of this document) that we have to keep in mind when doing widget styling. IE, the widgets don't have to look pretty in screen high-contrast mode, but they need to be usable.
Users can style color, fonts, images (both foreground images like arrows and background images like gradient shading) by just setting CSS rules and editing images. Note that this rule implies that all image paths (even things like arrows) occur in the CSS file, and then are transferred to <img> nodes for accessibility reasons.
More complicated styling, such as making rounded borders, requires users to modify the widget templates and/or javascript code. We aren't bending over backwards to make this kind of customization easy.
Dijit comes prepackaged with a theme called Tundra, which is a set of CSS rules and images to provide a standard look and feel to all the dijit widgets.
Users can design their own themes, and can use multiple themes on one page (each applying to a certain section of the page, like left and right.) This is not a rule so much as a design pattern that's possible due to rule #2 above.

See styling section for details.

Getting Started

What does the user have to do to use dojo in their pages?

One of the goals of the redesign is "less magic". Expose more things to the user, such as CSS settings, so that they can control them better. With that principle in mind, some things have changed about how you use dojo in a page:

<head>

In the head section, you need to include the CSS for dijit:

<link rel=stylesheet href="dijit/dijit.css" type="text/css">

(but see also the section below on themes)

Next you include dojo (which is now just core dojo stuff, nothing about widgets), and the widgets you are using. In addition, if you want dojo to automatically search the page for widget declarations then you need to include the parser. However, if you are creating your widgets programatically, you don't need to.

<script type="text/javascript" src="dojo/dojo.js"></script>

<script language="JavaScript" type="text/javascript">
	dojo.registerModulePath("dijit", "../dijit");	// not needed if dijit and dojo are sibling directories
	dojo.require("dijit.form.Button");
	dojo.require("dijit.form.Checkbox");
	dojo.require("dijit.util.parser");	// scan page for widgets and instantiate them
</script>

Note that widget auto-loading has been desupported. You have to dojo.require() the resources defining the widgets you want to use. (In the above example, dojo.require("dijit.form.Button") defines 3 widgets, the plain-button, drop-down-button, and the combo-button)

Widget Creation

Like before, you can create widgets by markup, or programatically.

Markup

If you want to create your widget by markup, then you need to include a parser, as documented above. It's this line:

dojo.require("dijit.util.parser"); // scan page for widgets and instantiate them

Then in your body you define widgets in a similar way to the old markup:

<button dojoType= "dijit.form.Button">

Note that unlike Dojo 0.4, the dojoType specifies the full path to the widget prototype. It's case sensitive, and namespaces (like "dojo:Button") are no longer supported. Parameters are specified as in Dojo 0.4:

<button dojoType="dijit.form.Button" type="submit" name="fred" onClick=    "foo" disabled>

Note, however, that there can be additional parsers that parse different markup. One suggestion from 3D2 was to encode the widget name and attributes inside the class and style attributes. Another parser might support XML syntax for declarations like <acme:Button disabled= "true">. But XML tends not to work very well inside of browsers, especially IE.

Programmatic

Create widgets via

var myWidget =   new dijit.form.Button(params, srcNodeRef)

The createWidget() call has been removed since multiple renderers are no longer supported (see next section).

* Unlike Dojo 0.4, programatic creation will not necessarily create the DOM node for you. You have to create the dom node first, and for a simple widget like a button that doesn't have a template, the DOM node you create must match the logical type of the widget (in this case, a <button> node). In addition, the node has to be part of the document already, or at least it has to have the theme CSS inherited.

Search

The Book of Dojo