Part 2: Dijit - The Dojo Widget Library

[inline:themeTester.png]

Dijit is a widget system layered on top of dojo. If you are new to the whole Dojo experience, Dijit is a good place to start. You can build amazing Web 2.0 GUI's using very little, or no, JavaScript.

You can use Dijit in one of two ways: declaratively by using special attributes inside of regular HTML tags, and programmatically through JavaScript. You have the same options either way. As we did in Part 1, we'll use declarative Dijit for all the examples in this part. Part 3 will show how to make the same calls programmatically.

Dijit comes bundled with its own theme, tundra, which brings a common design and color scheme to all the widgets. You can override the theme by container or by element to add nuance and flair.

Everything in Dijit is designed to be globally accessible -- to accommodate users with different languages and cultures as well as those with different abilities. Language translations, bi-directional text, and cultural representation of things like numbers and dates are all encapsulated within the widgets. Server interactions are done in a way that makes no assumptions about local conventions. All widgets are keyboard accessible and using the standard Dijit theme, usable in high-contrast mode as well as by screen readers. These features are baked in so that, as much as possible, all users are treated equally.

Dijit at a Glance

Form, Validation, Specialized Input

CheckBox	[inline:checkbox.png]
ComboBox	[inline:combo_box.png]
CurrencyTextBox	[inline:currency_textbox.png]
DateTextBox	[inline:date_textbox.png]
FilteringSelect	[inline:filtering_select.png]
InlineEditBox 0.9 - 1.0	[inline:inline_edit.png]
NumberSpinner	[inline:number_spinner.png]
NumberTextBox	[inline:number_textbox.png]
Slider	[inline:slider.png]
Textarea Textarea expands to fit content	[inline:textarea.png]
TextBox	[inline:textbox.png]
TimeTextBox	[inline:time_textbox.png]
ValidationTextBox	[inline:validating_textbox.png]

Layout

AccordionContainer	[inline:accordion_pane.png]
Border Container (new in 1.1)	[inline:border_container.png]
ContentPane	[inline:content_pane.png]
LayoutContainer (deprecated in 1.1)	[inline:layout_container.png]
SplitContainer (deprecated in 1.1)	[inline:split_container.png]
StackContainer	[inline:stack_container.png]
TabContainer	[inline:tab_container.png]

Command Control

Button, ComboButton, DropDownButton	[inline:button.png]
Menu	[inline:menu.png]
Toolbar	[inline:toolbar.png]

User Assistance and Feedback

Dialog	[inline:dialog_box.png]
TooltipDialog	[inline:tooltipDialog.png]
ProgressBar	[inline:progress_bar.png]
TitlePane Click arrow to expand/contract	[inline:title_pane.png]
Tooltip	[inline:tooltip.png]

Advanced Editing and Display

ColorPalette	[inline:color_picker.png]
Editor	[inline:editor.png]
Grid (1.0)	[inline:grid_terms.gif]
InlineEditBox 0.9 - 1.0	[inline:inline_edit.png]
Tree	[inline:tree.png]

Common Features

Attributes, Methods, Extension Points

Each Dijit component has interaction points, so you can customize them for your app. In order of complexity:

An attribute is a data element used for controlling display or behavior. For example, the label attribute of a ContentPane displays when that pane is part of a TabbedContainer.
Attributes are settable only at creation time. That means you can set them in the declarative tag, or in the new dijit.___() call. After that, you may not set them directly. Some attributes can be changed by a method call, usually with the name setAttributeName(). We'll note these in the guide where applicable.
A method is a function you call to control something. For example, in a NumberSpinner the user can click the Up and Down buttons to adjust a number. But you can call the method adjust() to do the same thing.
An extension point is a function you provide to override behavior. For example, a ValidationTextBox has an isValid() extension point. If your validation involves several fields or needs more power than regular expressions provide, you can create a new subclass of ValidationTextBox and provide your own isValid function.

Common Attributes

These attributes may be specified in any widget, in addition to all the normal HTML attributes (which are simply passed through unchanged to the finished widget).

Attribute	Type or values	Default	Description
domNode	Node	None	this is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's dojoAttachPoint syntax, but the domNode property is the canonical "top level" node in widget UI. In non-templated widgets, this will equal the srcNodeRef.
id	String	None	a unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.
lang	String	djConfig.locale or default provided by navigator object	overrides the page-wide setting to use a different language for this widget only. Must choose from bootstrapped languages in djConfig.extraLocale. It's usually best to default to the page settings so that the page can be localized with a single setting or the default. Use of this attribute is typically limited to demonstrations or pages with multiple languages besides the user's.
layoutAlign	String	Depends onorder within LayoutContainer	Only applies to Dijit components in dijit.layout.LayoutContainer. Possible values: "left", "right", "bottom", "top", and "client". The LayoutContainer takes its children marked as left/top/bottom/right, and lays them out along the edges of the box, and then it takes the child marked "client" and puts it into the remaining space in the middle.
srcNodeRef	Node	DOM Node which has the dojoType attribute.	Consider this attribute Read Only. In templated widgets, usually this node will disappear, replaced by a filled-in template.

Extension Points

Both methods and extension points are JavaScript functions, and the difference between them is a semantic one. We use the term method for "functions programmers normally call" and extension point for "functions the Dijit component normally calls". There's no technical reason you couldn't call an extension point yourself, or override a method yourself, but it makes little sense to do so.

You can easily provide an extension point function for declarative elements. As an example, here's how to extend a ValidationTextBox:

First, find the extension point on the appropriate Dijit page. In our case, it's dijit.form.ValidationTextBox.isValid
Copy the signature from the API documentation. For example, isValid() for ValidatingTextBox has signature function(/* Boolean*/ isFocused) and returns a boolean.
Then, use a dojo/method call directly in the markup, like this: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}
<div dojoType="dijit.form.ValidatingTextBox" isValid="my.form.isValid" ...>
<script type="dojo/method" event="isValid">
// Flip a coin to determine validity. *evil laughter!*
return Math.round(Math.random() * 100) % 2 == 0;
</script>
</div>

Of course, if your isValid function is the same for many widgets, you don't want to define it over and over. So alternatively:

Follow first 2 steps above
Write your function: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}
my.form.isValid = function(isFocused) {
// Flip a coin to determine validity. *evil laughter!*
return Math.round(Math.random() * 100) % 2 == 0;
}
Connect the function to the extension point through an HTML attribute: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}
<input dojoType="dijit.form.ValidatingTextBox" isValid="my.form.isValid" .../>

Other Things You Can Do With Dijit

You can change the style individual components, a Dijit class, or even create an entire theme spanning all Dijit components. The Themes and Design section tells you how.
You can create all Dijit components programmatically as well as declaratively (through markup). All attributes, methods and extension points are available through JavaScript.
You can create subclasses of existing Dijit classes, or create your own from scratch, described in the Writing Your Own Widget section.

Form, Validation, Specialized Input

The following widgets can be used in a FORM tag, in a dijit.form.Form widget, or outside of a form.

All form widgets implement the following attributes and methods. Many of them act as "shadow" attributes for their HTML counterparts, as in "name" or "id".

dijit.form._FormWidget Base class for all form widgets - that is, all widgets beginning with "dijit.form"
Attributes
disabled	Boolean	Should this widget respond to user input? In markup, this is specified as "disabled='disabled'", or just "disabled". Use setAttribute("disabled", true/false) to change after creation time.
intermediateChanges	Boolean	If true, trigger an onChange event every time setValue is called. If false, trigger onChange only when asked by the callee. For example, on Slider a true value would fire onChange events at each point of the mouse drag. False would trigger onChange only on mouseUp.
tabIndex	Integer	Order fields are traversed when user hits the tab key
Methods
focus	Set the focus on this widget
getValue	get the value of the widget.
setValue	set the value of the widget.
reset	resets the widget to it's initial value
undo	restore the value to the last value passed to onChange
Changed in 1.1
setAttribute	Controls all sorts of attributes for widgets like disabled, readonly, etc. The exception is value, which is generally still controlled via setValue()/getValue(). Methods like setDisabled() have been deprecated.
Extension Points
onChange	callback when value is changed

CheckBox, RadioButton	[inline:checkbox.png]
ComboBox	[inline:combo_box.png]
CurrencyTextBox	[inline:currency_textbox.png]
DateTextBox	[inline:date_textbox.png]
FilteringSelect	[inline:filtering_select.png]
InlineEditBox (0.9) For 1.0, see dijit.InlineEditBox	[inline:inline_edit.png]
NumberSpinner	[inline:number_spinner.png]
NumberTextBox	[inline:number_textbox.png]
Slider	[inline:slider.png]
Textarea Textarea expands to fit content	[inline:textarea.png]
TextBox	[inline:textbox.png]
TimeTextBox	[inline:time_textbox.png]
ValidationTextBox	[inline:validating_textbox.png]

Form Widget

Although you're not required to place Dijit form elements in a dijit.form.Form, doing so gets you some nice methods and extension points to use.

dijit.form.Form Adds conveniences to regular HTML form.
Methods
getValues	generate JSON structure from form values get widget values
isValid	Return true if every widget's isValid method returns true.
setValues	fill in form values from a JSON structure generate map from name --> [list of widgets with that name]
submit	programatically submit form
Extension Points
execute	User defined function to do stuff when the user hits the submit button

CheckBox, RadioButton, ToggleButton

dijit.form.CheckBox, dijit.form.RadioButton, and dijit.form.ToggleButton capture binary user-choices. Unlike command buttons, which do some action on being pressed, these buttons are more for form data. ToggleButtons can be used on Toolbars - the Bold button being the classic example - so they act a little like a data button, a little like a command button.

Examples

CheckBoxes in dijit are very intuitive and easy to use. Markup constructs for check boxes is the same as html but dojo provides more control and styling options than a conventional check box. The following example creates a CheckBox:

Are you a Developer

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Checkbox Example</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

        dojo.require("dojo.parser");

        dojo.require("dijit.form.CheckBox");

     </script>

</head>

<body class="tundra">

    <input id="cb" dojotype="dijit.form.CheckBox" 

           name="developer" checked="checked" value="on" 

           type="checkbox" /> 

    <label for="cb"> Are you a Developer </label> 

</body></html>

dijit.form.ToggleButton works very similarly to a checkbox, but requires including the "dijit.form.Button" module.

RadioButtons in dijit are also easy to create and use as the following example shows:

Metallica Extreme Slayer

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Radio Button Example</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

        dojo.require("dojo.parser");

        dojo.require("dijit.form.CheckBox");

    </script>

</head>

<body class="tundra">

    <input dojoType="dijit.form.RadioButton" id="sum1" name="album" 

           checked="checked" value="metallica" type="radio" />

           <label for="sum1"> Metallica </label> 

    <input dojotype="dijit.form.RadioButton" id="sum2"  name="album" 

           value="Extreme" type="radio" /> 

           <label for="sum2"> Extreme </label> 

    <input dojotype="dijit.form.RadioButton" id="sum3"  name="album" 

           value="Slayer" type="radio" /> 

           <label for="sum3"> Slayer </label> 

</body></html>

The RadioButton class is declared in the CheckBox.js file, hence you need to dojo.require() only dijit.form.CheckBox for RadioButtons to work.

dijit.form.CheckBox, dijit.form.RadioButton, dijit.form.ToggleButton Checkbox, RadioButton and ToggleButton capture binary user choices. Checkbox and RadioButton are like their HTML counterparts, while ToggleButton can be pushed in or out (like the Bold button in word processors).
Attributes
checked	String	Corresponds to the native HTML input element's attribute. In markup, specified as "checked='checked'" or just "checked". True if the button is depressed, or the checkbox is checked, or the radio button is selected, etc. Use setChecked() to change after creation time.
Methods
setValue(/* Boolean */ checked)	If true, turn button or box on.
Extension Points
onClick(/Event/ e)	Called when widget is clicked.

Accessibility

Keyboard

Tabbing moves through each form element, however, for radio buttons, tabbing will only go to the currently selected item in the radio group.

Widget	Keyboard Interaction
ToggleButton	Spacebar
Checkbox	Spacebar
RadioButton	Arrow keys: up or left arrow selects the previous radio button, down or right arrow selects the next.

ComboBox

The ComboBox is a hybrid between a SELECT combo box and a text field. Like a SELECT, you provide a list of acceptable values. Unlike SELECT, and like a text box, the user can ignore all the choices and type whatever they want. This is especially good for open-ended multiple choice questions. Rather than having two fields - a combo box and an Other text box - you can use just one field.

Note that SELECT's always have value/description pairs, e.g. the OPTION's value attribute and the OPTION's body text. ComboBoxes do not. They only pass their displayed text - just like a text box.

Examples

Using inlined data with the ComboBox is very much like using a native <select> tag:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Simple ComboBox</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.ComboBox");

       function setVal1(value) {

           console.debug("Selected "+value);

       }

   </script>

</head>

<body class="tundra">

        <select name="state1"

                dojoType="dijit.form.ComboBox"

                autocomplete="false"

                value="California"

                onChange="setVal1">

                <option selected="selected">California</option>

                <option >Illinois</option>

                <option >New York</option>

                <option >Texas</option>

        </select>

</body></html>

Name and autocomplete are passed through to the HTML. The value attribute enables you to set the default value. The option tags do not have hidden submit values; to use a hidden value, change your ComboBoxes to FilteringSelects.

Important: IE7 only uses the selected attribute of an option tag and ignores the value attribute on the select tag. For best results, set both the selected attribute on the default option and the value attribute on the select.

dojo.Data-Enabled ComboBox

ComboBox, FilteringSelect, Tree and Grid are dojo.data-Enabled widgets. This means rather than specifying all the data in the page - the OPTION's or tree nodes - you can have dojo.data fetch them from a server-based store. The unified dojo.data architecture, can get its data from various places - databases, web services, etc.. See the dojo.data manual section for complete details.

The code:

<div dojoType="dojo.data.ItemFileReadStore" jsId="stateStore"

              url="states.txt"></div>

... looks like a widget, but it's not. (Only dojoTypes from the module dijit.___ are widgets). This tag takes advantage of dojo.parser, which creates JavaScript objects by using standard HTML. You can read about Dojo.parser at Understanding the Parser in Part 3.

For this example, we'll use a fixed JSON data store. You can download it from states.txt below. Here's an excerpt:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

{

identifier:"abbreviation",

items: [

        {name:"Alabama", label:"Alabama",abbreviation:"AL"},

        {name:"Alaska", label:"Alaska",abbreviation:"AK"},

        {name:"American Samoa", label:"American Samoa",abbreviation:"AS"},

        {name:"Arizona", label:"Arizona",abbreviation:"AZ"},

The following example makes use of our data store:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Simple ComboBox</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.ComboBox");

       dojo.require("dojo.data.ItemFileReadStore");

       function setVal2(value) {

           console.debug("Selected "+value);

       }

   </script>

</head>

<body class="tundra">

        <div dojoType="dojo.data.ItemFileReadStore" jsId="stateStore" 

              url="states.txt"></div>

     <input dojoType="dijit.form.ComboBox"

                store="stateStore"

                value="California"

                searchAttr="name"

                name="state2"

                onChange="setVal2" />

</body></html>

jsId is the name of the global variable that the store is assigned to. url can be used to suck data out of particular URL, perhaps a web service. Instead of using the url attribute, you can embed your data directly (as is common in traditional server-side programming) using the data attribute.

dijit.form.ComboBox Auto-completing text box The drop down box's values are populated from an class called a data provider, which returns a list of values based on the characters that the user has typed into the input box. Some of the options to the ComboBox are actually arguments to the data provider.
Attributes
autoComplete	Boolean true	If you type in a partial string, and then tab out of the <input> box, automatically copy the first entry displayed in the drop down list to the <input> field
hasDownArrow	Boolean true	Set this textbox to have a down arrow button
ignoreCase	Boolean true	True if the ComboBox should ignore case when matching possible items.
pageSize	Integer Infinity	Argument to data provider. Specifies number of search results per page (before hitting "next" button)
query	Object {}	A query that can be passed to 'store' to initially filter the items, before doing further filtering based on searchAttr and the key.
searchAttr	String name	Searches pattern match against this field
searchDelay	Integer 100	Delay in milliseconds between when user types something and we start searching based on that value
store	Object	Reference to data provider object used by this ComboBox.

Accessibility

Keyboard

Action	Key
Open the menu of options (filtered by current input)	Down arrow
Navigate through the options	Up and down arrows
Pick an option	Enter
Close the menu of options without picking one	Esc

Known Issues (updated for 1.1)

JAWS 8 and Window-Eyes 6 may fail to read an option when it becomes highlighted. In Dojo 1.1 the Combobox was updated so that JAWS 9 will speak "editable combo" when the Combobox gets focus. However, there are some issues reading the highlighted choice. Generally JAWS 9 with Firefox 2 will only speak the part of the word that is currently selected in the textbox. For example, if you are working with a ComboBox containing the US state names and you type in an "I" to filter the list of states. If the user arrows down and highlights "Iowa" in the drop down list, "Iowa" will be displayed in the textbox with the "owa" portiion selected. JAWS 9 will speak, "owa" rather than "Iowa". This is not an issue with Firefox 3 and JAWS 9.

FilteringSelect

FilteringSelect is like an HTML SELECT tag, but is populated dynamically. It works very nicely with very large data sets because it can load and page data as needed. It also resembles ComboBox, but does not allow values outside of the provided ones.

When the user tries to submit invalid input (say if they choose an option, and the legal options change) the user gets a warning message, but the Select keeps text box input as is and also keeps the last valid submit value. If the user selects the text box and presses Escape on the keyboard, the text box reverts to the last valid value, corresponding to the hidden value. This change guarantees that you will always get a valid submit value.

Examples

First, here is a FilteringSelect with inlined data:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Filter Select Example 1</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

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

     </script>

</head>

<body class="tundra">

        <select dojoType="dijit.form.FilteringSelect"

        name="state3"

        autocomplete="false"

        value="CA">

                <option value="CA" selected="selected">California</option>

                <option value="IL" >Illinois</option>

                <option value="NY" >New York</option>

                <option value="TX" >Texas</option>

        </select>

</body></html>

As with ComboBox, has a value attribute. Unlike ComboBox, this value refers to the value attribute of the <option> tag. For example, if you set the value to AL, the text "Alabama" will appear in the text box on load. If you want to change the value attribute programmatically, use

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

dijit.byId("yourwidgetid").setValue("yourhiddenvalue")

Like ComboBox FilteringSelect is dojo.data-enabled. As with all dojo.data stores, you can add an identifier field to the top level of your data. The value of the identifier field tells the store which field in your data contains the submit value. Here's an example from states.txt:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

{

identifier:"abbreviation",

items: [

        {name:"Alabama", label:"Alabama",abbreviation:"AL"},

        ...

This code shows an identifier set to abbreviation. The identifier instructs the dojo.data store to set the submit value of the items in this store to the value of the attribute named abbreviation. In this example, the first item has a field named abbreviation with a value of AL. If one of your users selected that item in your FilteringSelect, the form would submit AL to your server.

Here's the corresponding FilteringSelect

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Data-Enabled FilteringSelect</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

        <script type="text/javascript">

       dojo.require("dojo.parser");

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

       dojo.require("dojo.data.ItemFileReadStore");

   </script>

</head>

<body class="tundra">

        <div dojoType="dojo.data.ItemFileReadStore" jsId="stateStore" 

              url="states.txt"></div>

        <form method="post">

                <input dojoType="dijit.form.FilteringSelect"

                    store="stateStore"

                        searchAttr="name"

                        name="state1"

                        autocomplete="true"

                        />

            <input type="submit" value="Go!" />

        </form>

</body></html>

The net result of the identifier is that you can easily set the submit attribute of any number of Selects using the same data without actually adding extra attributes to the Selects.

dijit.form.FilteringSelect
Attributes
autoComplete	Boolean true	If you type in a partial string, and then tab out of the <input> box, automatically copy the first entry displayed in the drop down list to the <input> field
hasDownArrow	Boolean true	Set this textbox to have a down arrow button/td>
ignoreCase	Boolean true	Does the ComboBox menu ignore case?
labelAttr	String searchAttr	String Searches pattern match against this field String Optional. The text that actually appears in the drop down. If not specified, the searchAttr text is used instead.
labelType	String text	"html" or "text"
pageSize	Integer Infinity	Argument to data provider. Specifies number of search results per page (before hitting "next" button)
query	Object {}	A query that can be passed to 'store' to initially filter the items, before doing further filtering based on searchAttr and the key.
searchAttr	String name	Searches pattern match against this field
searchDelay	Integer 100	Delay in milliseconds between when user types something and we start searching based on that value
store	String	Reference to data provider object used by this ComboBox.
Methods
setDisplayedValue(/String/ label)		Set label (and corresponding value) to "label"
setValue(/String/ value)		Set value (and corresponding label) to "value"

Accessibility

Keyboard

Action	Key
Open the menu of options (filtered by current input)	Down arrow
Navigate through the options	Up and down arrows
Pick an option	Enter
Close the menu of options without picking one	Esc

Known Issues

JAWS 8 and Window-Eyes 6 may fail to read an option when it becomes highlighted.

InlineEditBox (0.9)

In 1.0, dijit.form.InlineEditBox has been deprecated in favor of dijit.InlineEditBox

InlineEditBox is better described as a widget wrapper, which takes a child widget declared in markup and makes it inline-editable. This widget acts like a <div> tag when not in edit mode. When the contained rendered text is clicked, the widget enters an edit mode. In this mode, the previously displayed text is hidden, and another widget capable of editing text is made visible in its place.

Examples

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<title>InlineEdit Demo</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/0.9.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/0.9.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.xd.js" 

                djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.InlineEditBox");

       dojo.require("dijit.form.TextBox");

       function myHandler(idOfBox, value) {

           console.debug("Edited value from "+idOfBox+" is now "+value);

       }

     </script>

</head>

<body class="tundra">

        <span id="editable" style="font-size:larger;" 

                dojoType="dijit.form.InlineEditBox" 

                onChange="myHandler(this.id,arguments[0])">

        <input dojoType="dijit.form.TextBox" value="Edit me - I trigger the onChange callback">

    </span>

</body></html>

The outermost span is the InlineEditBox. The inner input tag is the TextBox widget. When a user loads the page, they see the text "Edit me - I trigger the onChange callback". If the user clicks the text, a TextBox widget containing the text "Edit me - I trigger the onChange callback" appears. When the user changes the value and clicks away, the TextBox disappears and the TextBox's contents appear inline.

InlineEditBox supports the textarea mode through the Textarea widget. By simply adding a Textarea inside the InlineEditBox HTML tag, you add inline-editing to the Textarea widget. Furthermore, by adding renderAsHtml=true, users can enter HTML into the Textarea and have it appear inline as rich text. :

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<title>InlineEdit Demo</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/0.9.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.xd.js" 

                djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.InlineEditBox");

       dojo.require("dijit.form.Textarea");

     </script>

</head>

<body class="tundra">

    <span id="areaEditable" dojoType="dijit.form.InlineEditBox" 

        renderAsHtml="true" autoSave="false">

                <textarea dojoType="dijit.form.Textarea">

                        I'm one big paragraph.  Go ahead and <i>edit</i> me.  <b>I dare you.</b> 

                        The quick brown fox jumped over the lazy dog.  Blah blah blah blah blah blah blah ...

                </textarea>

        </span>    

</body></html>

The outermost span in this code is the InlineEditBox. The inner textarea tag is the Textarea widget. When a user loads the page, they see the paragraph of rich text. If the user clicks the text, a Textarea widget containing the paragraph in plain text form appears. When the user changes the value and clicks away, the Textarea disappears and the Textarea's contents appear inline.

InlineEditBox can make any arbitrary widget that has a text value, or has the methods get/setDisplayedValue, inline. DateTextBox is an example of such a widget. This code shows a DateTextBox made inline in HTML:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<title>InlineEdit Demo</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/0.9.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.xd.js" 

                djConfig="parseOnLoad: true"></script>

    <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.InlineEditBox");

       dojo.require("dijit.form.DateTextBox");

     </script>

</head>

<body class="tundra">

    <p id="backgroundArea" dojoType="dijit.form.InlineEditBox" >

                <input name="date" value="2005-12-30"

                        dojoType="dijit.form.DateTextBox"

                        constraints={datePattern:'MM/dd/yy'}

                        lang="en-us"

                        required="true"

                        promptMessage="mm/dd/yy"

                        invalidMessage="Invalid date. Use mm/dd/yy format.">

</body></html>

The InlineEditBox can wrap around any widget that implements the following interface:

/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

/* void */ setTextValue(/*String*/ value) { ... }

String value = getTextValue() {... }

/* void */ focus() { ... }

The contained widget's setTextValue() method is called with the previously displayed text. When the Save button is pressed, the editing widget's getTextValue() method is called to retrieve the new text. After which, the editing widget is hidden, and the returned text is displayed. The focus method allows the editing widget to intelligently set focus to an appropriate node.

dijit.form.InlineEditBox Wrapper widget for holding click-to-edit text.
Methods
addChild	Process the given child widget, inserting it's dom node as a child of our dom node
getChildren	returns array of children widgets
hasChildren	returns true if widget has children
removeChild	removes the passed widget instance from this widget but does not destroy it

Accessibility

General Behavior

InlineEditBoxes are wrappers around the various types of dojo TextBoxes and Textareas. When they are activated the underlying dojo widget is activated. When they are "closed" they appear as text but are tab stops in the keyboard focus ring and have an accessible role of button. They can have autoSave or non-autoSave behavior. When an non-autoSave InlineEditBox is open it has associated Save and Cancel buttons. An autoSave InlineEditBox does not have these buttons and they act like miniature forms or dialogs, i.e pressing the Esc key will close the widget and pressing the Enter key will close the widget, saving and displaying the text.

Note that since InlineEditBoxes may be used on the page without a traditional label element, the developer should add a title attribute in order to provide a description that is available to screen reader users. The title will also be displayed by the browser when the user places the mouse over the element.

Keyboard

If the widget is closed.

Action	Key
Navigate to the next widget in the tab order.	Tab
Navigate to the prior widget in the tab order.	Shift+Tab
Open the widget.	Enter or spacebar

Note: The Esc key is ignored.

TextBox with autoSave specified and the TextBox is open:

Action	Key	Comments
Navigate to the next widget in the tab order.	Tab	The data is saved and the widget closes.
Navigate to the prior widget in the tab order.	Shift+Tab	The data is saved and the widget closes.
Close the TextBox, saving changes.	Enter	Keyboard focus is on the closed InlineEditBox.
Revert the last entry.	Esc	If the user has not entered data, the TextBox is closed.
Close the Textarea, discarding changes.	Esc	If the user has entered data, the Esc must be pressed two times; the first time the data will be reverted; the second time the TextBox will close.

Textarea with autoSave specified and the Textarea is open:

Action	Key	Comments
Navigate to the next widget in the tab order.	Tab (press twice in Firefox - see the Known Issues below)	The data is saved and the widget closes.
Navigate to the prior widget in the tab order.	Shift+Tab	The data is saved and the widget closes.
Enter a newline into the text.	Enter	There is no equivalent to the Enter key behavior of TextBoxes. The user would have to use something like Tab and Shift + Tab.
Revert the last entry.	Esc	If the user has not entered data, the Textarea is closed.
Close the Textarea, discarding changes.	Esc	If the user has entered data, the Esc must be pressed two times; the first time the data will be reverted; the second time the Textarea will close.

TextBox without autoSave specified, the TextBox is open, keyboard focus is in the edit field:

Action	Key	Comments
Navigate to the Save or Cancel button.	Tab	Focus changes to the Save button if the data has been changed, otherwise it moves to the Cancel button.
Navigate to the prior widget in the tab order.	Shift+Tab	The TextBox remains open.
Close the TextBox, saving changes.	Tab to the Save button, then press the Enter key	Keyboard focus is on the closed InlineEditBox.
Revert the last entry.	Esc	If the user has not entered data, the Esc key is ignored.
Close the Text Box, discarding changes.	Tab to the Cancel button, then press the Enter key.	Keyboard focus is on the closed InlineEditBox.

Note: The Enter key is ignored when focus is in the edit field.

Textarea without autoSave specified, the Textarea is open, keyboard focus is in the edit field:

Action	Key	Comments
Navigate to the Save or Cancel button.	Tab (press twice in Firefox - see the Known Issues below)	Focus changes to the Save button if the data has been changed, otherwise it moves to the Cancel button.
Navigate to the prior widget in the tab order.	Shift+Tab	The Textarea remains open.
Close the Textarea, saving changes.	Tab to the Save button, then press the Enter key	Keyboard focus is on the closed InlineEditBox.
Revert the last entry.	Esc	If the user has not entered data, the Esc key is ignored.
Close the Textarea, discarding changes.	Tab to the Cancel button, then press the Enter key.	Keyboard focus is on the closed InlineEditBox.

Note: Pressing the Enter key results in a newline being inserted into the edit field.

Known Issues

See the Comment for the Enter key in the information for autoSaving Text Areas above.
Ticket 3910: When Inline Text Boxes are opened, all the text should be selected.
On Firefox 2, the user must press the Tab key twice with focus in an textarea before keyboard focus moves to the next widget. This is a permanent restriction on Firefox 2. This is because the Dojo text area is implemented using the Firefox editor component in an iframe. This editor component implements usage of the tab key within the editor to indent text and shift-tab to outdent text. There is no keyboard mechanism in Firefox to move focus out of the editor. So, the dijit editor traps the tab key in the editor and sets focus to the editor iframe. From there pressing tab again will move to the next focusable item after the editor.

Screen Reader Issues

The InlineEditBox is implemented as a button. Since these are intended to be used "in-line" within text there is often no label element associated with the underlying control. For this reason, developers are encouraged to add a title attribute to InlineEditBoxes. The Window-Eyes screen reader will speak the title as part of the button description. JAWS has an option to speak different attributes on an button. A JAWS user may need to use the insert-v command to modify the behavior to speak the button title when working with Dojo InlineEditBoxes.

NumberSpinner

The Number Spinner, a familiar widget in GUI interfaces, makes integer entry easier when small adjustments are required. The down and up arrow buttons "spin" the number up and down. Furthermore, when you hold down the buttons, the spinning accelerates to make coarser adjustments easier.

Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

            "http://www.w3.org/TR/html4/strict.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<title>Number Spinner Demo</title>

    <style type="text/css">

        @import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";

        @import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"

    </style>

    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js" 

        djConfig="parseOnLoad: true"></script>

        <script type="text/javascript">

       dojo.require("dojo.parser");

       dojo.require("dijit.form.NumberSpinner");

    </script>

</head>

<body class="tundra">

        <input dojoType="dijit.form.NumberSpinner"

                value="1000"

                smallDelta="10"

                constraints="{min:9,max:1550,places:0}"

                maxlength="20"

                id="integerspinner2">

</body></html>

dijit.form.NumberSpinner Number Spinner
Attributes
constraints	Object {}	min and max properties are used for bounds. See ValidationTextBox for details.
defaultTimeout	Integer 500	number of milliseconds before a held key or button becomes typematic
invalidMessage	String locale dep.	The message to display if value is invalid. constraints: Object user-defined object needed to pass parameters to the validator functions
intermediateChanges	Boolean	If true, trigger an onChange event every time setValue is called. If false, trigger onChange only when asked by the callee. For example, on Slider a true value would fire onChange events at each point of the mouse drag. False would trigger onChange only on mouseUp.
largeDelta	Number 10	adjust the value by this much when spinning using the PgUp/Dn keys
promptMessage	String	Hint string
rangeMessage	String	The message to display if value is out-of-range
required	Boolean true	Defaults to true in NumberSpinner because the arrows won't work otherwise.
smallDelta	Number 1	adjust the value by this much when spinning using the arrow keys/buttons
timeoutChangeRate	Number 0.90	fraction of time used to change the typematic timer between events 1.0 means that each typematic event fires at defaultTimeout intervals < 1.0 means that each typematic event fires at an increasing faster rate
trim	Boolean false	Removes leading and trailing whitespace if true. Default is false.

Accessibility (added for 1.1 but true for 1.0 as well)

Keyboard

Action	Key
Interact with the number spinner	The textbox for the number spinner is in the tab order of the page. Press tab key to set focus into the number spinner textbox.
Increase the number spinner value by single increment	With focus in the number spinner textbox press the up arrow
Decrease number spinner value by single increment	With focus in the number spinner textbox press the down arrow
In the future pageup, pagedown, home and end may be implemented.

Slider

A slider is a scale with a handle you can drag up/down or left/right to select a value. Calling dojo.require("dijit.form.Slider") provides dijit.form.HorizontalSlider, dijit.form.VerticalSlider and all the rule and label classes.

Examples

One way you could show the user the value of your Slider is to create a textbox that the Slider fills when the user move

Part 2: Dijit - The Dojo Widget Library

Dijit at a Glance

Form, Validation, Specialized Input

Layout

Command Control

User Assistance and Feedback

Advanced Editing and Display

Common Features

Attributes, Methods, Extension Points

Common Attributes

Extension Points

Other Things You Can Do With Dijit

Form, Validation, Specialized Input

Changed in 1.1

Form Widget

CheckBox, RadioButton, ToggleButton

Examples

Accessibility

Keyboard

ComboBox

Examples

dojo.Data-Enabled ComboBox

Accessibility

Keyboard

Known Issues (updated for 1.1)

FilteringSelect

Examples

Accessibility

Keyboard

Known Issues

InlineEditBox (0.9)

Examples

Accessibility

General Behavior

Keyboard

Known Issues

Screen Reader Issues

NumberSpinner

Example

Accessibility (added for 1.1 but true for 1.0 as well)

Keyboard

Slider

Examples