Advanced Dijit Selects using Stores

In this tutorial, we will further explore Dijit's select widgets—particularly how to create instances programmatically, populating their drop-down lists from dojo/data stores.

Introduction

Previously in Getting
Selective with Dijit, you learned how Dijit enables you to quickly transform
a plain HTML select element into one of several feature-rich, skinnable widgets,
presenting a look and feel that is consistent with other Dijit widgets
across browsers.

However, that tutorial focused on creating these widgets declaratively
via markup reminiscent of standard HTML select elements. While that may
satisfy a wide range of use cases, there are plenty of others—such as
single-page rich internet applications pursuing a modular
design—which highly prefer programmatic widget instantiation.

It is clear from
othertutorials
that widgets can be created either declaratively or programmatically,
and indeed Dijit's select widgets are no exception. However, when creating
widgets programmatically, one does not ordinarily rely on pre-existing markup
in the page (perhaps a placeholder element, at most)—in which
case, from where shall we derive our drop-down list items?

Select Widgets and dojo/store

You should already be familiar with the concepts behind
dojo/store;
perhaps you have also already observed how some widgets interact with
stores.
Dijit's select widgets are also capable of working with dojo/store.

Select widgets have an optional store property;
passing a dojo/store instance to the
select widget via this property will instruct the widget to populate its
drop-down list with the items from the specified store. This works for all
three select widgets we've previously discussed: dijit/form/Select,
dijit/form/FilteringSelect, and dijit/form/ComboBox.

Fun fact: even when you create a dijit/form/FilteringSelect or
dijit/form/ComboBox from markup, the widget internally
converts it to a store!

To demonstrate select widgets and data stores working together, we will recreate
our select widgets for US states programmatically. To keep things simple,
we will use an instance of dojo/store/Memory
[ api
| ref ],
fetching its data from a JSON resource whose contents look something like this:

Notice that in addition to the name, there is an abbreviation.
It will become the "internal value" of each item.

When populating from a store, the value of a
dijit/form/Select or dijit/form/FilteringSelect
reports the identity of the selected item.
(This means that select widgets expect a store which implements getIdentity().)

Let's say that we have a web page set up with the Claro theme as seen in
previoustutorials,
and that the above JSON resource is available as
states.json within the same folder as the page.
We can instantiate an Memory to consume the resource, then
create a select widget referencing the store, like so:

When creating widgets programmatically, don't forget to call startup
on your widget instances once they have been placed in the document.
(The parser takes care of this for you in the case of declarative instantiation.)
Forgetting to call startup is a very common mistake, and while its
effects may vary from widget to widget, you can generally expect odd behavior to
ensue. For example, if we were to forget to call startup in the
dijit/form/Select example above, you would find that the drop-down
list would be empty.

Notice how similar these examples are—the primary difference being which
widget is required and instantiated. Aside from that, there
are only a few differences:

We add maxHeight: -1 for Select, to prevent the drop-down
menu from causing the entire page to grow in size; FilteringSelect and
ComboBox already do this by default.

We add placeHolder text for FilteringSelect and
ComboBox—Select does not support this.

labelAttr, the attribute used for the label, is specified for the Select—
for ComboBox and FilteringSelect labelAttr defaults to searchAttr,
and searchAttr defaults to "name", so we didn't bother specifying it.

Select needs an explicit width setting.

You may have noticed that our dijit/form/Select example does not
have an empty-valued "Select a state" item this time around.
The smoothest way to resolve this would be to also include this item in the store.
For the purposes of this example, however, we have omitted it in favor of a
more natural presentation of the other two widgets, while still being able to
use the same store and JSON resource for all three.

We have now observed how all three Dijit select widgets can be created
programmatically, populating their lists from a data store via the
store property. Next we will take a closer look at some behaviors
and capabilities that set these widgets apart from one another.

Note: it is technically possible to declaratively create Dijit select
widgets using stores as well; however, doing so is not recommended, since
it requires exposing the store as a global object in the web page or
application. Declarative instantiation of select widgets is best reserved for
instances which take advantage of their ability to be created with
markup very similar to that of a standard HTML select element.
It is far more common and appropriate to use stores in conjunction with
programmatically-created select widgets.

Using Stores with FilteringSelect and ComboBox

It makes sense to look at dijit/form/FilteringSelect and
dijit/form/ComboBox together, as both inherit the same codebase
and thus share the same behavior in terms of how they interact with a data store.

While FilteringSelect and ComboBox behave identically within the confines of this
discussion, please remember that these two widgets report value
differently—see the
previous tutorial on select widgets
for details.

In the previous tutorial, we only looked at the most important widget properties
to get up and running. There are a few additional properties of interest
particularly when working with stores:

searchAttr:
Name of the attribute to match text field input against when filtering
the list; defaults to "name".

pageSize:
Limits how many list options will be displayed at a time—if the
number of results exceeds this limit, a special item will be added to the list
at each end, for moving to the next or previous "page".
The default is Infinity (no limit).

Note that pageSize can also be used when creating widgets from
markup—we did not introduce it in the previous tutorial simply because
it is not a feature normally encountered in a standard HTML select element.

Noting the properties above gives us some insight as to the behavior of these
two widgets—they do not rely upon the store's label attribute(s).
Rather, they expect you to specify which item attribute
to use for searching and displaying items in the drop-down list.

In our states drop-down example above, notice that we did not specify
searchAttr; this is because our data items already have a
name attribute, which contains what we want to search against and
display in the list—therefore, the example "just works".

Using Stores with dijit/form/Select

We noted earlier that when using stores, dijit/form/Select and
dijit/form/FilteringSelect associate their value with
the identity of the currently-selected item. However,
dijit/form/Select possesses an important limitation: it is
implemented in such a way that it does not handle non-string item identities well.
Particularly, setting the current value of the widget programmatically via
select.set("value", id) will not work with non-string
(e.g. numeric) identities.

For best results, only use dijit/form/Select with a store whose
items' identities are strings.

Another important detail: when changing the store referenced by a
dijit/form/Select widget after initialization, you might be
inclined to call widget.set("store", newStore) as with other
select widgets, but this will not work with
dijit/form/Select—instead, call
widget.setStore(newStore).

Programmatically Creating dijit/form/Select without a Store

Thus far, this tutorial has been dedicated to the use of stores with Dijit's
select widgets, but its underlying purpose has been to demonstrate programmatic
instantiation of these widgets. Along those lines, dijit/form/Select
provides an alternative approach that does not require the use of a store: the
options property.

The options property accepts an array of objects,
each of which may include the following properties:

label:
The text to appear in this list item; analogous to the
innerHTML of an option element. This is reflected in
the widget's displayedValue when the item is selected.

value:
The "internal" value represented by this list item; analogous to the
value attribute of an option element. This is
reflected in the widget's value when the item is selected.

selected:(optional) If true, indicates that this item should be
initially selected in the widget; analogous to the selected
attribute of an option element.

disabled:(optional) If true, indicates that this item should not be
selectable in the drop-down list; analogous to the disabled
attribute of an option element.

Let's take a look at an example of the options array in action,
with an alternate (and abridged) version of our states drop-down:

As you can see, this achieves a result comparable to the previous
dijit/form/Select example, without using a store.
This can be useful in instances where you wish to create the widget
programmatically, with a list of options that is either short and static,
or simple to generate procedurally.

It is also possible to later add and remove individual options using the
addOption and removeOption methods, each of which can
be passed either a single object or an array of objects. Additionally, you
can replace the list entirely by calling
set("options", arrayOfObjects). However, due to a limitation
of the implementation, you will need to call startup again
for this to take effect (which is otherwise not a standard practice).

Conclusion

Dijit offers a number of widgets for enriching the user experience normally
found in HTML select elements. These widgets can be created via markup with
minimal changes to ordinary HTML code, but can also be instantiated
programmatically—primarily through cooperation with dojo/store
stores. At the most basic level, you can easily swap between these widgets
with minimal code changes, but as we have seen, each one has its own
particular behaviors and strengths.

After reading a number of these tutorials, you should feel more comfortable with
the basic building blocks Dijit provides for creating rich, functional
user interfaces. We hope this encourages you to start exploring and building
awesome applications with Dojo!