ComboBox → dijit.form.ComboBox

Name changes

Examples

This section shows you how to migrate your 0.4 ComboBoxes to 0.9. To better understand the steps necessary to migrate a Web page using a ComboBox, you will take the widgets in the 0.4 test_ComboBox.html and rewrite them in a format suited to 0.9.

ComboBox #1: inlined data, autocomplete=false, default value of CA (California)

As with the 0.4 ComboBox, using inlined data with the 0.9 ComboBox is very much like using a native <select> tag. Listings 1 and 2 give the syntax for 0.4 ComboBox and 0.9 ComboBox respectively:

Listing 1. 0.4 ComboBox syntax

<select name="state"

	dojoType="combobox" 
	autocomplete="false"
	onValueChanged="setVal1"
>
	<option value="CA" selected>California</option>

	...
</select>

Listing 2. 0.9 ComboBox syntax

<select	name="state1"
	dojoType="dijit.form.ComboBox"
	autocomplete="false"

	value="California"
	onChange="setVal1"
>
	<option selected>California</option>
	...
</select>

Only the dojoType and onValueChanged→onChange actually changed here; name, and autocomplete still apply to ComboBox. 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.

ComboBox #2: dataUrl, autocomplete=true

0.9 uses the new unified dojo.data architecture. Consequently, the old dataProvider architecture for ComboBox is no longer part of the 0.9 ComboBox.

In 0.4, instead of creating your own dataProvider, you might have instead used one of the built in JavaScript array dataProviders, dojo.widget.basicComboBoxDataProvider or dojo.widget.incrementalComboBoxDataProvider. This section gives you a general idea of how to apply the 0.9 dojo.data architecture to the 0.9 ComboBox and also details the specific case of porting your ComboBox from dojo.widget.basicComboBoxDataProvider JavaScript arrays to the 0.9 dojo.data.ItemFileReadStore and its unique format.

Create a dojo.data store in the markup

In 0.9 you create a new tag in the HTML for the dojo.data store. Listing 3 shows a store that would load an item file called comboBoxData.js:

Listing 3. Creating a dojo.data.store in the HTML

jsId is the name of the global variable that the store is assigned to. url is just like the dataUrl from the 0.4 ComboBox. Instead of using the url attribute, you can embed your data directly (as is common in traditional server-side programming) using the data attribute. Refer to the next section for details on the 0.9 ItemFileReadStore format.

Migrate your JSON data

This section is specific to the case that you wrote JavaScript arrays to your ComboBox using the default dateProviders.

Whether you had a static file of JavaScript arrays, a database Web proxy dedicated to returning JavaScript arrays, or a dynamic Web page that wrote the JavaScript arrays to the client on load, you need to migrate the format in which these applications wrote so that they will be compatible with the 0.9 ItemFileReadStore. Listings 4 and 5 visually demonstrate the differences in the 0.4 array syntax and the 0.9 item file syntax:

Listing 4. 0.4 JavaScript array syntax

[
	["Alabama","AL"],
	["Alaska","AK"],
	["American Samoa","AS"],
	["Arizona","AZ"],
	...
]

Listing 5. 0.9 JSON syntax

{
	identifier:"abbreviation",
	items: [
		{name:"Alabama", abbreviation:"AL"},
		{name:"Alaska", abbreviation:"AK"},
		{name:"American Samoa", abbreviation:"AS"},
		{name:"Arizona", abbreviation:"AZ"},
		...
	]
}

Notice how the item format has changed. The data is encapsulated by an outer set of curly braces {}, and is further encapsulated in a named array called items. The data set has an identifier attribute whose value is the name of the attribute that distinguishes each item. In 0.9, each item is further encapsulated by {} instead of [], enabling you to name your attributes and write them in any order.

Migrate ComboBox #2

Now that you have created the appropriate dojo.data store, you can migrate the ComboBox's attributes. Compare the old ComboBox with its 0.9 equivalent in Listings 6 and 7:

Listing 6. 0.4 ComboBox syntax

<input dojoType="ComboBox" value="this should never be seen - it is replaced!"

	dataUrl="comboBoxData.js" style="width: 300px;" name="foo.bar"
	onValueChanged="setVal2"
>

Listing 7. 0.9 ComboBox syntax

<div dojoType="dojo.data.ItemFileReadStore" jsId="stateStore" url="comboBoxData.js">
<input dojoType="dijit.form.ComboBox"
	store="stateStore"
	value="California"
	searchAttr="name"

	name="state2"
	onChange="setVal2"
>

Select → dijit.form.FilteringSelect

0.9 introduced reverse lookup capabilities to setValue and setDisplayedValue in the Select API. If you have been changing the value of your Selects programmatically with setAllValues by keeping your own reverse lookup arrays, you should revisit your code and take advantage of the reverse lookup capability.

Concerning the UI, Select also handles invalid input differently. In 0.4 Select cleared the textbox and submit value on invalid input. Now the user gets a warning message, but the Select keeps textbox input as is and also keeps the last valid submit value. If the user selects the textbox and presses Escape on the keyboard, the textbox reverts to the last valid value, corresponding to the hidden value. This change guarantees that you will always get a valid submit value from your 0.9 FilteringSelects. Keep this UI change in mind as you migrate your applications.

Name changes

Migrating a Web page with a 0.4 Select to 0.9 is very similar to migrating a ComboBox, with these differences:

Examples

This section shows you how to migrate your 0.4 Selects to 0.9. To better understand the steps necessary to migrate a Web page using a Select, you will take the widgets in the 0.4 test_Select.html and rewrite them in a format suited to 0.9.

Select #1: inlined data, autocomplete=false:

Building a 0.9 FilteringSelect from inline <option> tags is almost identical to building a 0.9 ComboBox. Listings 8 and 9 show the differences:

Listing 8. 0.4 Select syntax

<select dojoType="Select" 
	name="state3" 
	autocomplete="false"
	onValueChanged="setVal1"
	style="width: 300px;">
	<option value="AL">Alabama</option>
	...
</select>

Listing 9. 0.9 FilteringSelect syntax

<select	dojoType="dijit.form.FilteringSelect"
	name="state3"
	autocomplete="false"
	onChange="setValue('value1', arguments[0]);" value="CA"

>
	<option value="AL">Alabama</option>
	...
</select>

As with 0.9 ComboBox, 0.9 FilteringSelect adds 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 textbox on load. If you want to change the value attribute programmatically, use dijit.byId("yourwidgetid").setValue("yourhiddenvalue").

Important: do not confuse setValue with the onChange setValue in Listing 9: that setValue refers to a global setValue in the 0.9 test_FilteringSelect.html, in line with the setVal1 in the 0.4 test, and is not part of the widget.

Select #2: dataUrl, autocomplete=true:

You will want to follow the steps for creating a dojo.data store in the markup and migrating your JSON data, mentioned in the ComboBox #2 section, before continuing.

Add an identifier field to your data

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. Listing 10 gives an example from dijit/tests/form/comboBoxData.json:

Listing 10. comboBoxData.json with an identifier

{
identifier:"abbreviation",
items: [
	{name:"Alabama", label:"<img width='97px' height='127px' src='images/Alabama.jpg'/>Alabama",abbreviation:"AL"},
	...

Listing 10 demonstrates an identifer set to abbreviation. The identifer 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.

Important: unlike FilteringSelect, ComboBox does not have a hidden submit value, so ignores the identifier attribute.

Listing 11 and 12 show how to migrate a 0.4 Select with a dataUrl to a 0.9 FilteringSelect that takes advantage of the identifier attribute:

Listing 11. 0.4 Select syntax

input dojoType="Select" value="this should never be seen - it is replaced!"
	dataUrl="comboBoxData.js" style="width: 300px;" name="state1"
	onValueChanged="setVal2"
>

Listing 12. 0.9 FilteringSelect syntax

<div dojoType="dojo.data.ItemFileReadStore" jsId="stateStore" url="comboBoxData.js">

<input dojoType="dijit.form.FilteringSelect"
	searchAttr="name"
	name="state1"
	autocomplete="true"
	onChange="setValue('value2', arguments[0]);"
>

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.