X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..HEAD:/src/form/field/ComboBox.js diff --git a/src/form/field/ComboBox.js b/src/form/field/ComboBox.js index 584ebcfd..834656ce 100644 --- a/src/form/field/ComboBox.js +++ b/src/form/field/ComboBox.js @@ -1,10 +1,23 @@ +/* + +This file is part of Ext JS 4 + +Copyright (c) 2011 Sencha Inc + +Contact: http://www.sencha.com/contact + +GNU General Public License Usage +This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html. + +If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact. + +*/ /** - * @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. * - * A ComboBox is like a combination of a traditional HTML text `<input>` field and a `<select>` + * A ComboBox is like a combination of a traditional HTML text `` field and a `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. - *
- *

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 query ({@link Ext.data.Store#baseParam baseParam} name for the store) - * as it will be passed on the querystring (defaults to 'query') + * @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 for queries. Acceptable values are: - *
+ * 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 {@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 select the first result gathered by the data store (defaults - * to true). A false value would require a manual selection from the dropdown list to set the components value - * unless the value of ({@link #typeAhead}) were true. + * @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: '' + * }); */ /** @@ -291,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 `