Clear Up
SharpKit Reference

ComboBox Class

A combobox control with support for autocomplete, remote loading, and many other features.

A ComboBox is like a combination of a traditional HTML text <input> field and a <select> field; the user is able to type freely into the field, and/or pick values from a dropdown selection list. The user can input any value by default, even if it does not appear in the selection list; to prevent free-form values and restrict them to items in the list, set forceSelection to true.

The selection list's options are populated from any Ext.data.Store, including remote stores. The data items in the store are mapped to each option's displayed text and backing value via the valueField and displayField configurations, respectively.

If your store is not remote, i.e. it depends only on local data and is loaded up front, you should be sure to set the queryMode to 'local', as this will improve responsiveness for the user.

Example usage:

  
// The data store containing the list of states
            var states = Ext.create('Ext.data.Store', {
            fields: ['abbr', 'name'],
            data : [
            {"abbr":"AL", "name":"Alabama"},
            {"abbr":"AK", "name":"Alaska"},
            {"abbr":"AZ", "name":"Arizona"}
            //...
            ]
            });
            // Create the combo box, attached to the states data store
            Ext.create('Ext.form.ComboBox', {
            fieldLabel: 'Choose State',
            store: states,
            queryMode: 'local',
            displayField: 'name',
            valueField: 'abbr',
            renderTo: Ext.getBody()
            });
            

Events

To do something when something in ComboBox is selected, configure the select event:

  
var cb = Ext.create('Ext.form.ComboBox', {
            // all of your config options
            listeners:{
            scope: yourScope,
            'select': yourFunction
            }
            });
            // Alternatively, you can assign events after the object is created:
            var cb = new Ext.form.field.ComboBox(yourOptions);
            cb.on('select', yourFunction, yourScope);
            

Multiple Selection

ComboBox also allows selection of multiple items from the list; to enable multi-selection set the multiSelect config to true.

Filtered Stores

If you have a local store that is already filtered, you can use the lastQuery config option to prevent the store from having the filter being cleared on first expand.

Customized combobox

Both the text shown in dropdown menu and text field can be easily customized:

  
var states = Ext.create('Ext.data.Store', {
            fields: ['abbr', 'name'],
            data : [
            {"abbr":"AL", "name":"Alabama"},
            {"abbr":"AK", "name":"Alaska"},
            {"abbr":"AZ", "name":"Arizona"}
            ]
            });
            Ext.create('Ext.form.ComboBox', {
            fieldLabel: 'Choose State',
            store: states,
            queryMode: 'local',
            valueField: 'abbr',
            renderTo: Ext.getBody(),
            // Template for the dropdown menu.
            // Note the use of "x-boundlist-item" class,
            // this is required to make the items selectable.
            tpl: Ext.create('Ext.XTemplate',
            '<tpl for=".">',
            '<div class="x-boundlist-item">{abbr} - {name}</div>',
            '</tpl>'
            ),
            // template for the content inside text field
            displayTpl: Ext.create('Ext.XTemplate',
            '<tpl for=".">',
            '{abbr} - {name}',
            '</tpl>'
            )
            });
            

See also the listConfig option for additional configuration of the dropdown.

Namespace: Ext.form.field

Derived Types

Fields

Name Description
allQuery The text query to send to the server to return all records for the list with no filtering Defaults to: ""
autoSelect true to automatically highlight the first result gathered by the data store in the dropdown list when it is opened. A false value would cause nothing in the list to be highlighted automatically, so the user would have to manually highlight an item before pressing the enter or tab key to select it (unless the value of (typeAhead) were true), or use the mouse to select a value. Defaults to: true
defaultListConfig Set of options that will be used as defaults for the user-configured listConfig object. Defaults to: {loadingHeight: 70, minWidth: 70, maxHeight: 300, shadow: "sides"}
delimiter The character(s) used to separate the display values of multiple selected items when multiSelect = true. Defaults to: ", "
displayField The underlying data field name to bind to this ComboBox. See also valueField . Defaults to: "text"
forceSelection true to restrict the selected value to one of the values in the list, false to allow the user to set arbitrary text into the field. Defaults to: false
growToLongestValue false to not allow the component to resize itself when its data changes (and its grow property is true) Defaults to: true
hiddenDataCls CSS class used to find the hiddenDataEl Defaults to: "x-hide-display "
hiddenName The name of an underlying hidden field which will be synchronized with the underlying value of the combo. This option is useful if the combo is part of a form element doing a regular form post. The hidden field will not be created unless a hiddenName is specified. Defaults to: ""
listConfig An optional set of configuration properties that will be passed to the Ext.view.BoundList's constructor. Any configuration that is valid for BoundList can be included. Some of the more useful ones are:
  • cls - defaults to empty
  • emptyText - defaults to empty string
  • itemSelector - defaults to the value defined in BoundList
  • loadingText - defaults to 'Loading...'
  • minWidth - defaults to 70
  • maxWidth - defaults to undefined
  • maxHeight - defaults to 300
  • resizable - defaults to false
  • shadow - defaults to 'sides'
  • width - defaults to undefined (automatically set to the width of the ComboBox field if matchFieldWidth is true)
  • minChars The minimum number of characters the user must type before autocomplete and typeAhead activate. Defaults to 4 if queryMode = 'remote' or 0 if queryMode = 'local', does not apply if editable = false.
    multiSelect If set to true, allows the combo field to hold more than one value at a time, and allows selecting multiple items from the dropdown list. The combo's text field will show all selected values separated by the delimiter. Defaults to: false
    pageSize If greater than 0, a Ext.toolbar.Paging is displayed in the footer of the dropdown list and the filter queries will execute with page start and limit parameters. Only applies when queryMode = 'remote'. Defaults to: 0
    queryCaching When true, this prevents the combo from re-querying (either locally or remotely) when the current query is the same as the previous query. Defaults to: true
    queryDelay The length of time in milliseconds to delay between the start of typing and sending the query to filter the dropdown list. Defaults to 500 if queryMode = 'remote' or 10 if queryMode = 'local'
    queryMode The mode in which the ComboBox uses the configured Store. Acceptable values are:
  • 'remote' :

    In queryMode: 'remote', the ComboBox loads its Store dynamically based upon user interaction.

    This is typically used for "autocomplete" type inputs, and after the user finishes typing, the Store is loaded.

    A parameter containing the typed string is sent in the load request. The default parameter name for the input string is query, but this can be configured using the queryParam config.

    In queryMode: 'remote', the Store may be configured with

    remoteFilter:
                true
    , and further filters may be programatically added to the Store which are then passed with every load request which allows the server to further refine the returned dataset.

    Typically, in an autocomplete situation, hideTrigger is configured true because it has no meaning for autocomplete.

  • 'local' :

    ComboBox loads local data

        
    var combo = new Ext.form.field.ComboBox({
                renderTo: document.body,
                queryMode: 'local',
                store: new Ext.data.ArrayStore({
                id: 0,
                fields: [
                'myId',  // numeric value is the key
                'displayText'
                ],
                data: [[1, 'item1'], [2, 'item2']]  // data is local
                }),
                valueField: 'myId',
                displayField: 'displayText',
                triggerAction: 'all'
                });
                
  • Defaults to: "remote"
    queryParam Name of the parameter used by the Store to pass the typed string when the ComboBox is configured with queryMode: 'remote'. If explicitly set to a falsy value it will not be sent. Defaults to: "query"
    selectOnTab Whether the Tab key should select the currently highlighted item. Defaults to: true
    store The data source to which this combo is bound. Acceptable values for this property are:
  • any Store subclass
  • an Array : Arrays will be converted to a Ext.data.Store internally, automatically generating field names to work with all data components.

    • 1-dimensional array : (e.g., ['Foo','Bar'])

      A 1-dimensional array will automatically be expanded (each array item will be used for both the combo valueField and displayField)

    • 2-dimensional array : (e.g., [['f','Foo'],['b','Bar']])

      For a multi-dimensional array, the value in index 0 of each item will be assumed to be the combo valueField, while the value at index 1 is assumed to be the combo displayField.

  • See also queryMode.
    transform The id, DOM node or Ext.Element of an existing HTML <select> element to convert into a ComboBox. The target select's options will be used to build the options in the ComboBox dropdown; a configured store will take precedence over this.
    triggerAction The action to execute when the trigger is clicked.
  • 'all' :

    run the query specified by the allQuery config option

  • 'query' :

    run the query using the raw value.

  • See also queryParam . Defaults to: "all"
    typeAhead true to populate and autoselect the remainder of the text being typed after a configurable delay (typeAheadDelay) if it matches a known value. Defaults to: false
    typeAheadDelay The length of time in milliseconds to wait until the typeahead text is displayed if typeAhead = true Defaults to: 250
    valueField The underlying data value name to bind to this ComboBox. Note: use of a valueField requires the user to make a selection in order for a value to be mapped. See also displayField . Defaults to match the value of the displayField config.
    valueNotFoundText When using a name/value combo, if the value passed to setValue is not found in the store, valueNotFoundText will be displayed as the field text if defined. If this default text is used, it means there is no value set and no validation will occur on this field.

    Methods

    Name Description
    bindStore(object, object) Binds a store to this instance.
    bindStoreListeners(AbstractStore) Binds listeners for this component to the store. By default it will add anything bound by the getStoreListeners method, however it can be overridden in a subclass to provide any more complicated handling.
    clearValue() Clears any value currently set in the ComboBox.
    doQuery(JsString, object, object) Executes a query to filter the dropdown list. Fires the beforequery event prior to performing the query allowing the query action to be canceled if needed.
    findRecord(JsString, object) Finds the record by searching for a specific field/value combination.
    findRecordByDisplay(object) Finds the record by searching values in the displayField.
    findRecordByValue(object) Finds the record by searching values in the valueField.
    getStore() Returns the store associated with this ComboBox.
    getStoreListeners() Gets the listeners to bind to a new store.
    onBindStore(AbstractStore, bool) Template method, it is called when a new store is bound to the current instance.
    onUnbindStore(AbstractStore, bool) Template method, it is called when an existing store is unbound from the current instance.
    select(object) Selects an item by a Model, or by a key value.
    unbindStoreListeners(AbstractStore) Unbinds listeners from this component to the store. By default it will remove anything bound by the bindStoreListeners method, however it can be overridden in a subclass to provide any more complicated handling.

    Properties

    Name Description
    lastQuery The value of the match string used to filter the store. Delete this property to force a requery. Example use:
    var combo = new Ext.form.field.ComboBox({
                ...
                queryMode: 'remote',
                listeners: {
                // delete the previous query in the beforequery event or set
                // combo.lastQuery = null (this will reload the store the next time it expands)
                beforequery: function(qe){
                delete qe.combo.lastQuery;
                }
                }
                });
                
    To make sure the filter in the store is not cleared the first time the ComboBox trigger is used configure the combo with lastQuery=''. Example use:
    var combo = new Ext.form.field.ComboBox({
                ...
                queryMode: 'local',
                triggerAction: 'all',
                lastQuery: ''
                });
                
    © Copyright 2005-2011 SharpKit. All rights reserved.