Provides main functionality of ComboBox widget
See the dijit/form/ComboBoxMixin reference documentation for more information.
The node to display the popup around. Can be set via a data-dojo-attach-point assignment. If missing, then domNode will be used.
Will set CSS class dijitUpArrow, dijitDownArrow, dijitRightArrow etc. on this node depending on where the drop down is set to be positioned. Can be set via a data-dojo-attach-point assignment. If missing, then _buttonNode will be used.
The button/icon/node to click to display the drop down. Can be set via a data-dojo-attach-point assignment. If missing, then either focusNode or domNode (if focusNode is also missing) will be used.
The node to set the aria-expanded class on. Also sets popupActive class but that will be removed in 2.0. Can be set via a data-dojo-attach-point assignment. If missing, then focusNode or _buttonNode (if focusNode is missing) will be used.
When set to false, the click events will not be stopped, in case you want to use them in your subclass
If user types 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
Set to true to make the drop down at least as wide as this widget. Set to false if the drop down should just be its default width.
The widget to display as a popup. This widget must be defined before the startup function is called.
This variable controls the position of the drop down. It's an array of strings with the following values:
The list is positions is tried, in order, until a position is found where the drop down fits within the viewport.
Mixin to the store's fetch. For example, to set the sort order of the ComboBox menu, pass:
{ sort: [{attribute:"name",descending: true}] }
To override the default queryOptions so that deep=false, do:
{ queryOptions: {ignoreCase: true, deep: false} }
Set to true to make the drop down exactly as wide as this widget. Overrides autoWidth.
Set this textbox to have a down arrow button, to display the drop down list. Defaults to true.
One of: "first", "all" or "none".
If the ComboBox/FilteringSelect opens with the search results and the searched
string can be found, it will be highlighted. If set to "all"
then will probably want to change queryExpr parameter to '${0}'
Highlighting is only performed when labelType is "text", so as to not
interfere with any HTML markup an HTML label might contain.
Set true if the query should ignore case when matching possible items
This is the item returned by the dojo/store/api/Store implementation that provides the data for this ComboBox, it's the currently selected item.
The entries in the drop down list come from this attribute in the dojo.data items. If not specified, the searchAttr attribute is used instead.
Specifies how to interpret the labelAttr in the data store items. Can be "html" or "text".
Alternate to specifying a store. Id of a dijit/form/DataList widget.
The max height for our dropdown. Any dropdown taller than this will have scrollbars. Set to 0 for no max height, or -1 to limit height to available space in viewport
Argument to data provider. Specifies maximum number of search results to return per query
A query that can be passed to store to initially filter the items.
ComboBox overwrites any reference to the searchAttr and sets it to the queryExpr with the user's input substituted.
This specifies what query is sent to the data store,
based on what the user has typed. Changing this expression will modify
whether the results are only exact matches, a "starting with" match,
etc.
${0} will be substituted for the user text.
* is used for wildcards.
${0}* means "starts with", *${0}* means "contains", ${0} means "is"
Search for items in the data store where this attribute (in the item) matches what the user typed
Delay in milliseconds between when user types something and we start searching based on that value
Reference to data provider object used by this ComboBox.
Should be dojo/store/api/Store, but dojo/data/api/Read supported for backwards compatibility.
a11y code that puts the highlighted option in the textbox. This way screen readers will know what is happening in the menu.
| Parameter | Type | Description |
|---|---|---|
| node | Node |
Fill in the textbox with the first item from the drop down list, and highlight the characters that were auto-completed. For example, if user typed "CA" and the drop down list appeared, the textbox would be changed to "California" and "ifornia" would be highlighted.
| Parameter | Type | Description |
|---|---|---|
| text | String |
| Parameter | Type | Description |
|---|---|---|
| element | DomNode |
Helper for postMixInProperties() to set this.value based on data inlined into the markup. Returns the attribute name in the item (in dijit/form/_ComboBoxDataStore) to use as the value.
Callback when a search completes.
| Parameter | Type | Description |
|---|---|---|
| results | Object | |
| query | Object | |
| options | Object |
Helper function to convert a simple pattern to a regular expression for matching.
Returns a regular expression object that conforms to the defined conversion rules. For example:
and so on.
| Parameter | Type | Description |
|---|---|---|
| pattern | dojo/string | A simple matching pattern to convert that follows basic rules:
To use a \ as a character in the string, it must be escaped. So in the pattern it should be represented by \ to be treated as an ordinary \ character instead of an escape. |
Handles input (keyboard/paste) events
| Parameter | Type | Description |
|---|---|---|
| evt | Event |
Menu callback function, called when an item in the menu is selected.
| Parameter | Type | Description |
|---|---|---|
| target | DomNode |
| Parameter | Type | Description |
|---|---|---|
| element | DomNode | |
| location | Number |
| Parameter | Type | Description |
|---|---|---|
| value | Boolean |
| Parameter | Type | Description |
|---|---|---|
| val | Boolean |
Set the displayed valued in the input box, and the hidden value that gets submitted, based on a dojo.data store item.
Users shouldn't call this function; they should be calling set('item', value)
| Parameter | Type | Description |
|---|---|---|
| item | item | |
| priorityChange | Boolean |
Optional
|
| displayedValue | String |
Optional
|
Hook so set('value', value) works.
Sets the value of the select.
| Parameter | Type | Description |
|---|---|---|
| value | String | |
| priorityChange | Boolean |
Optional
|
| displayedValue | String |
Optional
|
| item | item |
Optional
|
Starts a search for elements matching key (key=="" means to return all items), and calls _openResultList() when the search completes, to display the results.
| Parameter | Type | Description |
|---|---|---|
| key | String |
Closes the drop down on this widget
| Parameter | Type | Description |
|---|---|---|
| focus | Boolean | If true, refocuses the button widget |
Highlights the string entered by the user in the menu. By default this highlights the first occurrence found. Override this method to implement your custom highlighting.
| Parameter | Type | Description |
|---|---|---|
| label | String | |
| find | String |
Dropdown widget class used to select a date/time. Subclasses should specify this.
Returns true if the dropdown exists and it's data is loaded. This can be overridden in order to force a call to loadDropDown().
Computes the label to display based on the dojo.data store item.
| Parameter | Type | Description |
|---|---|---|
| item | Object | The item from the store |
| store | dojo/store/api/Store | The store. |
The label that the ComboBox should display
Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then opens the drop down. This is basically a callback when the user presses the down arrow button to open the drop down.
Deferred for the drop down widget that fires when drop down is created and loaded
Creates the drop down if it doesn't exist, loads the data if there's an href and it hasn't been loaded yet, and then calls the given callback.
| Parameter | Type | Description |
|---|---|---|
| loadCallback | Function |
Opens the dropdown for this widget. To be called only when this.dropDown has been created and is ready to display (ie, it's data is loaded).
return value of dijit/popup.open()
Callback when the user presses the down arrow button or presses the down arrow key to open/close the drop down. Toggle the drop-down widget; if it is up, close it, if not, open it
Called magically when focus has shifted away from this widget and it's dropdown
Callback when the user mousedown/touchstart on the arrow icon.
| Parameter | Type | Description |
|---|---|---|
| e | Event |
Callback on mouseup/touchend after mousedown/touchstart on the arrow icon. Note that this function is called regardless of what node the event occurred on (but only after a mousedown/touchstart on the arrow).
If the drop down is a simple menu and the cursor is over the menu, we execute it, otherwise, we focus our drop down widget. If the event is missing, then we are not a mouseup event.
This is useful for the common mouse movement pattern
with native browser <select> nodes:
| Parameter | Type | Description |
|---|---|---|
| e | Event |
Optional
|
Callback when the user presses a key while focused on the button node
| Parameter | Type | Description |
|---|---|---|
| e | Event |
Callback when a search completes.
| Parameter | Type | Description |
|---|---|---|
| results | Object | An array of items from the originating _SearchMixin's store. |
| query | Object | A copy of the originating _SearchMixin's query property. |
| options | Object | The additional parameters sent to the originating _SearchMixin's store, including: start, count, queryOptions. |