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:
"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:
"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:
"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:
/* 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;}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:
"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:
"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;}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
"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.InlineEditBoxInlineEditBox 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
"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. :
"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:
"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;}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 |
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. |
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. |
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
"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 moves the Slider. The following code fills in a simple textbox called horizontalSliderValue.
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Slider Example 1</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.Slider");
</script>
</head>
<body class="tundra">
<div id="horizontalSlider" dojoType="dijit.form.HorizontalSlider"
value="5" minimum="-10" maximum="10" discreteValues="11"
intermediateChanges="true"
onChange="dojo.byId('horizontalSlider').value = arguments[0];"
handleSrc="http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/images/preciseSliderThumb.png"
></div>
</body></html>
You can point the handleSrc image to wherever you want. If you want to use the default handle image, just remove the handleSrc.
For a horizontal slider, you can use the HorizintalRule and HorizontalRuleLabels to create your ruler marks programmatically, reducing the amount of data being transferred over the wire:
- 20%
- 40%
- 60%
- 80%
- 0%
- 50%
- 100%
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Slider Example 2</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.Slider");
</script>
</head>
<body class="tundra">
<div id="horizontalSlider" dojoType="dijit.form.HorizontalSlider"
value="5" minimum="-10" maximum="10" discreteValues="11"
intermediateChanges="true"
showButtons="true">
<div dojoType="dijit.form.HorizontalRuleLabels" container="topDecoration"
style="height:1.2em;font-size:75%;color:gray;"></div>
<ol dojoType="dijit.form.HorizontalRuleLabels" container="topDecoration"
style="height:1em;font-size:75%;color:gray;">
<li> </li>
<li>20%</li>
<li>40%</li>
<li>60%</li>
<li>80%</li>
<li> </li>
</ol>
<div dojoType="dijit.form.HorizontalRule" container="bottomDecoration"
count=5 style="height:5px;"></div>
<ol dojoType="dijit.form.HorizontalRuleLabels" container="bottomDecoration"
style="height:1em;font-size:75%;color:gray;">
<li>0%</li>
<li>50%</li>
<li>100%</li>
</ol>
</div>
</div>
</body></html>
The VerticalSlider API is identical to the HorizontalSlider API. You can use the VerticalRule class to create vertical ruler marks.
|
dijit.form.HorizontalSlider, dijit.form.VerticalSlider
A form widget that allows one to select a value with a horizontally (or vertically) draggable image
|
||
|
Attributes
|
||
| clickSelect | boolean true |
If clicking the progress bar changes the value or not |
| discreteValues | integer Infinity |
The maximum allowed values dispersed evenly between minimum and maximum (inclusive). |
| intermediateChanges | Boolean false |
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. |
| maximum | integer 100 |
The maximum allowed value. |
| minimum | integer 0 |
The minimum value allowed. |
| pageIncrement | integer 2 |
The amount of change with pageup/pagedown |
| showButtons | boolean true |
Show increment/decrement buttons at the ends of the slider? |
|
Methods
|
||
| setValue((/*Number*/ value, /*Boolean, optional*/ priorityChange) | Regular setValue, but if priorityChange is true, then it is more likely to be animated. | |
|
dijit.form.HorizontalRule, dijit.form.VerticalRule
Create hash marks for the Horizontal/Vertical slider
|
||
|
Attributes
|
||
| container | Node containerNode |
If this is a child widget, connect it to this parent node |
| count | Integer 3 |
|