A combobox control with support for autocomplete, remote-loading, paging and many other features.
+ *A ComboBox works in a similar manner to a traditional HTML <select> field. The difference is + * that to submit the {@link #valueField}, you must specify a {@link #hiddenName} to create a hidden input + * field to hold the value of the valueField. The {@link #displayField} is shown in the text field + * which is named according to the {@link #name}.
+ *Events
+ *To do something when something in ComboBox is selected, configure the select event:
+var cb = new 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.ComboBox(yourOptions);
+cb.on('select', yourFunction, yourScope);
+ * ComboBox in Grid
+ *If using a ComboBox in an {@link Ext.grid.EditorGridPanel Editor Grid} a {@link Ext.grid.Column#renderer renderer} + * will be needed to show the displayField when the editor is not active. Set up the renderer manually, or implement + * a reusable render, for example:
+// create reusable renderer
+Ext.util.Format.comboRenderer = function(combo){
+ return function(value){
+ var record = combo.findRecord(combo.{@link #valueField}, value);
+ return record ? record.get(combo.{@link #displayField}) : combo.{@link #valueNotFoundText};
+ }
+}
+
+// create the combo instance
+var combo = new Ext.form.ComboBox({
+ {@link #typeAhead}: true,
+ {@link #triggerAction}: 'all',
+ {@link #lazyRender}:true,
+ {@link #mode}: 'local',
+ {@link #store}: new Ext.data.ArrayStore({
+ id: 0,
+ fields: [
+ 'myId',
+ 'displayText'
+ ],
+ data: [[1, 'item1'], [2, 'item2']]
+ }),
+ {@link #valueField}: 'myId',
+ {@link #displayField}: 'displayText'
+});
+
+// snippet of column model used within grid
+var cm = new Ext.grid.ColumnModel([{
+ ...
+ },{
+ header: "Some Header",
+ dataIndex: 'whatever',
+ width: 130,
+ editor: combo, // specify reference to combo instance
+ renderer: Ext.util.Format.comboRenderer(combo) // pass combo instance to reusable renderer
+ },
+ ...
+]);
+ * Filtering
+ *A ComboBox {@link #doQuery uses filtering itself}, for information about filtering the ComboBox + * store manually see {@link #lastQuery}.
+ * @constructor + * Create a new ComboBox. + * @param {Object} config Configuration options + * @xtype combo + */ +Ext.form.ComboBox = Ext.extend(Ext.form.TriggerField, { + /** + * @cfg {Mixed} transform The id, DOM node or element of an existing HTML SELECT to convert to a ComboBox. + * Note that if you specify this and the combo is going to be in an {@link Ext.form.BasicForm} or + * {@link Ext.form.FormPanel}, you must also set {@link #lazyRender} = true. + */ + /** + * @cfg {Boolean} lazyRender true to prevent the ComboBox from rendering until requested + * (should always be used when rendering into an {@link Ext.Editor} (e.g. {@link Ext.grid.EditorGridPanel Grids}), + * defaults to false). + */ + /** + * @cfg {String/Object} autoCreateA {@link Ext.DomHelper DomHelper} element spec, or true for a default + * element spec. Used to create the {@link Ext.Component#getEl Element} which will encapsulate this Component. + * See {@link Ext.Component#autoEl autoEl} for details. Defaults to:
+ *{tag: "input", type: "text", size: "24", autocomplete: "off"}See also {@link #mode}.
+ */ + /** + * @cfg {String} title If supplied, a header element is created containing this text and added into the top of + * the dropdown list (defaults to undefined, with no header element) + */ + + // private + defaultAutoCreate : {tag: "input", type: "text", size: "24", autocomplete: "off"}, + /** + * @cfg {Number} listWidth The width (used as a parameter to {@link Ext.Element#setWidth}) of the dropdown + * list (defaults to the width of the ComboBox field). See also {@link #minListWidth} + */ + /** + * @cfg {String} displayField The underlying {@link Ext.data.Field#name data field name} to bind to this + * ComboBox (defaults to undefined if {@link #mode} = 'remote' or 'text' if + * {@link #transform transforming a select} a select). + *See also {@link #valueField}.
+ *Note: if using a ComboBox in an {@link Ext.grid.EditorGridPanel Editor Grid} a + * {@link Ext.grid.Column#renderer renderer} will be needed to show the displayField when the editor is not + * active.
+ */ + /** + * @cfg {String} valueField The underlying {@link Ext.data.Field#name data value name} to bind to this + * ComboBox (defaults to undefined if {@link #mode} = 'remote' or 'value' if + * {@link #transform transforming a select}). + *Note: use of a valueField requires the user to make a selection in order for a value to be + * mapped. See also {@link #hiddenName}, {@link #hiddenValue}, and {@link #displayField}.
+ */ + /** + * @cfg {String} hiddenName If specified, a hidden form field with this name is dynamically generated to store the + * field's data value (defaults to the underlying DOM element's name). Required for the combo's value to automatically + * post during a form submission. See also {@link #valueField}. + *Note: the hidden field's id will also default to this name if {@link #hiddenId} is not specified. + * The ComboBox {@link Ext.Component#id id} and the {@link #hiddenId} should be different, since + * no two DOM nodes should share the same id. So, if the ComboBox {@link Ext.form.Field#name name} and + * hiddenName are the same, you should specify a unique {@link #hiddenId}.
+ */ + /** + * @cfg {String} hiddenId If {@link #hiddenName} is specified, hiddenId can also be provided + * to give the hidden field a unique id (defaults to the {@link #hiddenName}). The hiddenId + * and combo {@link Ext.Component#id id} should be different, since no two DOM + * nodes should share the same id. + */ + /** + * @cfg {String} hiddenValue Sets the initial value of the hidden field if {@link #hiddenName} is + * specified to contain the selected {@link #valueField}, from the Store. Defaults to the configured + * {@link Ext.form.Field#value value}. + */ + /** + * @cfg {String} listClass The CSS class to add to the predefined 'x-combo-list' class + * applied the dropdown list element (defaults to ''). + */ + listClass : '', + /** + * @cfg {String} selectedClass CSS class to apply to the selected item in the dropdown list + * (defaults to 'x-combo-selected') + */ + selectedClass : 'x-combo-selected', + /** + * @cfg {String} listEmptyText The empty text to display in the data view if no items are found. + * (defaults to '') + */ + listEmptyText: '', + /** + * @cfg {String} triggerClass An additional CSS class used to style the trigger button. The trigger will always + * get the class 'x-form-trigger' and triggerClass will be appended if specified + * (defaults to 'x-form-arrow-trigger' which displays a downward arrow icon). + */ + triggerClass : 'x-form-arrow-trigger', + /** + * @cfg {Boolean/String} shadow true or "sides" for the default effect, "frame" for + * 4-way shadow, and "drop" for bottom-right + */ + shadow : 'sides', + /** + * @cfg {String} listAlign A valid anchor position value. See {@link Ext.Element#alignTo} for details + * on supported anchor positions (defaults to 'tl-bl?') + */ + listAlign : 'tl-bl?', + /** + * @cfg {Number} maxHeight The maximum height in pixels of the dropdown list before scrollbars are shown + * (defaults to 300) + */ + maxHeight : 300, + /** + * @cfg {Number} minHeight The minimum height in pixels of the dropdown list when the list is constrained by its + * distance to the viewport edges (defaults to 90) + */ + minHeight : 90, + /** + * @cfg {String} triggerAction The action to execute when the trigger is clicked. + *{@link #doQuery run the query} using the {@link Ext.form.Field#getRawValue raw value}.
{@link #doQuery run the query} specified by the {@link #allQuery} config option
See also {@link #queryParam}.
Automatically loads the {@link #store} the first time the trigger + * is clicked. If you do not want the store to be automatically loaded the first time the trigger is + * clicked, set to 'local' and manually load the store. To force a requery of the store + * every time the trigger is clicked see {@link #lastQuery}.
ComboBox loads local data
+ *
+var combo = new Ext.form.ComboBox({
+ renderTo: document.body,
+ mode: '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'
+});
+ *
+var combo = new Ext.form.ComboBox({
+ ...
+ mode: '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;
+ }
+ }
+});
+ *
+var combo = new Ext.form.ComboBox({
+ ...
+ mode: 'local',
+ triggerAction: 'all',
+ lastQuery: ''
+});
+ * combo : Ext.form.ComboBox query : String forceAll : Boolean cancel : Boolean The template string, or {@link Ext.XTemplate} instance to + * use to display each item in the dropdown list. The dropdown list is displayed in a + * DataView. See {@link #view}.
+ *The default template string is:
+ '<tpl for="."><div class="x-combo-list-item">{' + this.displayField + '}</div></tpl>'
+ * Override the default value to create custom UI layouts for items in the list. + * For example:
+ '<tpl for="."><div ext:qtip="{state}. {nick}" class="x-combo-list-item">{state}</div></tpl>'
+ * The template must contain one or more substitution parameters using field + * names from the Combo's {@link #store Store}. In the example above an + *
ext:qtipattribute is added to display other fields from the Store. + *
To preserve the default visual look of list items, add the CSS class name + *
x-combo-list-itemto the template's container element. + *
Also see {@link #itemSelector} for additional details.
+ */ + this.tpl = 'A simple CSS selector (e.g. div.some-class or span:first-child) that will be + * used to determine what nodes the {@link #view Ext.DataView} which handles the dropdown + * display will be working with.
+ *Note: this setting is required if a custom XTemplate has been + * specified in {@link #tpl} which assigns a class other than
'x-combo-list-item'+ * to dropdown list items + */ + } + + /** + * The {@link Ext.DataView DataView} used to display the ComboBox's options. + * @type Ext.DataView + */ + this.view = new Ext.DataView({ + applyTo: this.innerList, + tpl: this.tpl, + singleSelect: true, + selectedClass: this.selectedClass, + itemSelector: this.itemSelector || '.' + cls + '-item', + emptyText: this.listEmptyText + }); + + this.mon(this.view, 'click', this.onViewClick, this); + + this.bindStore(this.store, true); + + if(this.resizable){ + this.resizer = new Ext.Resizable(this.list, { + pinned:true, handles:'se' + }); + this.mon(this.resizer, 'resize', function(r, w, h){ + this.maxHeight = h-this.handleHeight-this.list.getFrameWidth('tb')-this.assetHeight; + this.listWidth = w; + this.innerList.setWidth(w - this.list.getFrameWidth('lr')); + this.restrictHeight(); + }, this); + + this[this.pageSize?'footer':'innerList'].setStyle('margin-bottom', this.handleHeight+'px'); + } + } + }, + + /** + *
Returns the element used to house this ComboBox's pop-up list. Defaults to the document body.
+ * A custom implementation may be provided as a configuration option if the floating list needs to be rendered + * to a different Element. An example might be rendering the list inside a Menu so that clicking + * the list does not hide the Menu:
+var store = new Ext.data.ArrayStore({
+ autoDestroy: true,
+ fields: ['initials', 'fullname'],
+ data : [
+ ['FF', 'Fred Flintstone'],
+ ['BR', 'Barney Rubble']
+ ]
+});
+
+var combo = new Ext.form.ComboBox({
+ store: store,
+ displayField: 'fullname',
+ emptyText: 'Select a name...',
+ forceSelection: true,
+ getListParent: function() {
+ return this.el.up('.x-menu');
+ },
+ iconCls: 'no-icon', //use iconCls if placing within menu to shift to right side of menu
+ mode: 'local',
+ selectOnFocus: true,
+ triggerAction: 'all',
+ typeAhead: true,
+ width: 135
+});
+
+var menu = new Ext.menu.Menu({
+ id: 'mainMenu',
+ items: [
+ combo // A Field in a Menu
+ ]
+});
+