X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/form/field/ComboBox.js diff --git a/src/form/field/ComboBox.js b/src/form/field/ComboBox.js index f646337e..834656ce 100644 --- a/src/form/field/ComboBox.js +++ b/src/form/field/ComboBox.js @@ -13,8 +13,7 @@ If you are unsure which license is appropriate for your use, please contact the */ /** - * @class Ext.form.field.ComboBox - * @extends Ext.form.field.Picker + * @docauthor Jason Johnston * * A combobox control with support for autocomplete, remote loading, and many other features. * @@ -30,10 +29,9 @@ If you are unsure which license is appropriate for your use, please contact the * 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 {@link #queryMode} to `'local'`, as this will improve responsiveness for the user. * - * {@img Ext.form.ComboBox/Ext.form.ComboBox.png Ext.form.ComboBox component} - * - * ## Example usage: + * # Example usage: * + * @example * // The data store containing the list of states * var states = Ext.create('Ext.data.Store', { * fields: ['abbr', 'name'], @@ -55,7 +53,7 @@ If you are unsure which license is appropriate for your use, please contact the * renderTo: Ext.getBody() * }); * - * ## Events + * # Events * * To do something when something in ComboBox is selected, configure the select event: * @@ -71,12 +69,10 @@ If you are unsure which license is appropriate for your use, please contact the * var cb = new Ext.form.field.ComboBox(yourOptions); * cb.on('select', yourFunction, yourScope); * - * ## Multiple Selection + * # Multiple Selection * * ComboBox also allows selection of multiple items from the list; to enable multi-selection set the * {@link #multiSelect} config to `true`. - * - * @docauthor Jason Johnston */ Ext.define('Ext.form.field.ComboBox', { extend:'Ext.form.field.Picker', @@ -85,213 +81,267 @@ Ext.define('Ext.form.field.ComboBox', { alias: ['widget.combobox', 'widget.combo'], /** - * @cfg {String} triggerCls - * An additional CSS class used to style the trigger button. The trigger will always get the - * {@link #triggerBaseCls} by default and triggerCls will be appended if specified. - * Defaults to 'x-form-arrow-trigger' for ComboBox. + * @cfg {String} [triggerCls='x-form-arrow-trigger'] + * An additional CSS class used to style the trigger button. The trigger will always get the {@link #triggerBaseCls} + * by default and `triggerCls` will be **appended** if specified. */ triggerCls: Ext.baseCSSPrefix + 'form-arrow-trigger', /** - * @cfg {Ext.data.Store/Array} store The data source to which this combo is bound (defaults to undefined). - * Acceptable values for this property are: - *
    - *
  • any {@link Ext.data.Store Store} subclass
    • - *
  • an Array : Arrays will be converted to a {@link Ext.data.Store} internally, - * automatically generating {@link Ext.data.Field#name 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 - * {@link #valueField} and {@link #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 - * {@link #valueField}, while the value at index 1 is assumed to be the combo {@link #displayField}. - *
- *

See also {@link #queryMode}.

+ * @private + * @cfg {String} + * CSS class used to find the {@link #hiddenDataEl} + */ + hiddenDataCls: Ext.baseCSSPrefix + 'hide-display ' + Ext.baseCSSPrefix + 'form-data-hidden', + + /** + * @override + */ + fieldSubTpl: [ + '', + 'size="{size}" ', + 'tabIndex="{tabIdx}" ', + 'class="{fieldCls} {typeCls}" autocomplete="off" />', + '', + { + compiled: true, + disableFormats: true + } + ], + + getSubTplData: function(){ + var me = this; + Ext.applyIf(me.subTplData, { + hiddenDataCls: me.hiddenDataCls + }); + return me.callParent(arguments); + }, + + afterRender: function(){ + var me = this; + me.callParent(arguments); + me.setHiddenValue(me.value); + }, + + /** + * @cfg {Ext.data.Store/Array} store + * The data source to which this combo is bound. Acceptable values for this property are: + * + * - **any {@link Ext.data.Store Store} subclass** + * - **an Array** : Arrays will be converted to a {@link Ext.data.Store} internally, automatically generating + * {@link Ext.data.Field#name 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 + * {@link #valueField} and {@link #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 + * {@link #valueField}, while the value at index 1 is assumed to be the combo {@link #displayField}. + * + * See also {@link #queryMode}. */ /** * @cfg {Boolean} 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 {@link #delimiter}. (Defaults to false.) + * 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 + * {@link #delimiter}. */ multiSelect: false, /** * @cfg {String} delimiter - * The character(s) used to separate the {@link #displayField display values} of multiple selected items - * when {@link #multiSelect} = true. Defaults to ', '. + * The character(s) used to separate the {@link #displayField display values} of multiple selected items when + * `{@link #multiSelect} = true`. */ delimiter: ', ', /** - * @cfg {String} displayField The underlying {@link Ext.data.Field#name data field name} to bind to this - * ComboBox (defaults to 'text'). - *

See also {@link #valueField}.

+ * @cfg {String} displayField + * The underlying {@link Ext.data.Field#name data field name} to bind to this ComboBox. + * + * See also `{@link #valueField}`. */ displayField: 'text', /** - * @cfg {String} valueField - * @required + * @cfg {String} valueField (required) * The underlying {@link Ext.data.Field#name data value name} to bind to this ComboBox (defaults to match * the value of the {@link #displayField} config). - *

Note: use of a valueField requires the user to make a selection in order for a value to be - * mapped. See also {@link #displayField}.

+ * + * **Note**: use of a `valueField` requires the user to make a selection in order for a value to be mapped. See also + * `{@link #displayField}`. */ /** - * @cfg {String} triggerAction The action to execute when the trigger is clicked. - *
    - *
  • 'all' : Default - *

    {@link #doQuery run the query} specified by the {@link #allQuery} config option

    • - *
  • 'query' : - *

    {@link #doQuery run the query} using the {@link Ext.form.field.Base#getRawValue raw value}.

    • - *
- *

See also {@link #queryParam}.

+ * @cfg {String} triggerAction + * The action to execute when the trigger is clicked. + * + * - **`'all'`** : + * + * {@link #doQuery run the query} specified by the `{@link #allQuery}` config option + * + * - **`'query'`** : + * + * {@link #doQuery run the query} using the {@link Ext.form.field.Base#getRawValue raw value}. + * + * See also `{@link #queryParam}`. */ triggerAction: 'all', /** - * @cfg {String} allQuery The text query to send to the server to return all records for the list - * with no filtering (defaults to '') + * @cfg {String} allQuery + * The text query to send to the server to return all records for the list with no filtering */ allQuery: '', /** - * @cfg {String} queryParam Name of the parameter used by the Store to pass the typed string when the ComboBox is configured with - * {@link #queryMode}: 'remote' (defaults to 'query'). If explicitly set to a falsy value it will - * not be sent. + * @cfg {String} queryParam + * Name of the parameter used by the Store to pass the typed string when the ComboBox is configured with + * `{@link #queryMode}: 'remote'`. If explicitly set to a falsy value it will not be sent. */ queryParam: 'query', /** * @cfg {String} queryMode * The mode in which the ComboBox uses the configured Store. Acceptable values are: - *
    - *
  • 'remote' : Default - *

    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 {@link Ext.data.Store#load load}ed.

    - *

    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 {@link #queryParam} config.

    - *

    In queryMode: 'remote', the Store may be configured with {@link Ext.data.Store#remoteFilter 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, {@link #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'
-});
-     *
    • - *
+ * + * - **`'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 {@link + * Ext.data.Store#load load}ed. + * + * 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 {@link #queryParam} config. + * + * In `queryMode: 'remote'`, the Store may be configured with `{@link Ext.data.Store#remoteFilter 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, {@link #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' + * }); */ queryMode: 'remote', queryCaching: true, /** - * @cfg {Number} pageSize If greater than 0, a {@link Ext.toolbar.Paging} is displayed in the - * footer of the dropdown list and the {@link #doQuery filter queries} will execute with page start and - * {@link Ext.toolbar.Paging#pageSize limit} parameters. Only applies when {@link #queryMode} = 'remote' - * (defaults to 0). + * @cfg {Number} pageSize + * If greater than `0`, a {@link Ext.toolbar.Paging} is displayed in the footer of the dropdown list and the + * {@link #doQuery filter queries} will execute with page start and {@link Ext.view.BoundList#pageSize limit} + * parameters. Only applies when `{@link #queryMode} = 'remote'`. */ pageSize: 0, /** - * @cfg {Number} 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 {@link #queryMode} = 'remote' - * or 10 if {@link #queryMode} = 'local') + * @cfg {Number} 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 `{@link #queryMode} = 'remote'` or `10` if `{@link #queryMode} = 'local'`) */ /** - * @cfg {Number} minChars The minimum number of characters the user must type before autocomplete and - * {@link #typeAhead} activate (defaults to 4 if {@link #queryMode} = 'remote' or 0 if - * {@link #queryMode} = 'local', does not apply if {@link Ext.form.field.Trigger#editable editable} = false). + * @cfg {Number} minChars + * The minimum number of characters the user must type before autocomplete and {@link #typeAhead} activate (defaults + * to `4` if `{@link #queryMode} = 'remote'` or `0` if `{@link #queryMode} = 'local'`, does not apply if + * `{@link Ext.form.field.Trigger#editable editable} = false`). */ /** - * @cfg {Boolean} autoSelect true to automatically highlight the first result gathered by the data store - * in the dropdown list when it is opened. (Defaults to true). 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 {@link #selectOnTab tab} key to select it (unless the value of ({@link #typeAhead}) were true), - * or use the mouse to select a value. + * @cfg {Boolean} 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 {@link #selectOnTab tab} key to + * select it (unless the value of ({@link #typeAhead}) were true), or use the mouse to select a value. */ autoSelect: true, /** - * @cfg {Boolean} typeAhead true to populate and autoselect the remainder of the text being - * typed after a configurable delay ({@link #typeAheadDelay}) if it matches a known value (defaults - * to false) + * @cfg {Boolean} typeAhead + * `true` to populate and autoselect the remainder of the text being typed after a configurable delay + * ({@link #typeAheadDelay}) if it matches a known value. */ typeAhead: false, /** - * @cfg {Number} typeAheadDelay The length of time in milliseconds to wait until the typeahead text is displayed - * if {@link #typeAhead} = true (defaults to 250) + * @cfg {Number} typeAheadDelay + * The length of time in milliseconds to wait until the typeahead text is displayed if `{@link #typeAhead} = true` */ typeAheadDelay: 250, /** * @cfg {Boolean} selectOnTab - * Whether the Tab key should select the currently highlighted item. Defaults to true. + * Whether the Tab key should select the currently highlighted item. */ selectOnTab: true, /** - * @cfg {Boolean} 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) + * @cfg {Boolean} 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. */ forceSelection: false, /** - * @cfg {String} 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 (defaults to undefined). If this - * default text is used, it means there is no value set and no validation will occur on this field. + * @cfg {String} 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. */ /** - * 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: ''
-});
-     *
- * @property lastQuery - * @type String + * @property {String} 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: '' + * }); */ /** @@ -308,31 +358,28 @@ var combo = new Ext.form.field.ComboBox({ }, /** - * @cfg {Mixed} transform - * The id, DOM node or {@link Ext.core.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 {@link #store} will take precedence over this. + * @cfg {String/HTMLElement/Ext.Element} transform + * The id, DOM node or {@link Ext.Element} of an existing HTML `