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 'field1' if - * {@link #transform transforming a select} or if the {@link #store field name is autogenerated based on - * the store configuration}). - *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 'field2' if - * {@link #transform transforming a select} or if the {@link #store field name is autogenerated based on - * the store configuration}). - *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/Array} listAlign A valid anchor position value. See {@link Ext.Element#alignTo} for details - * on supported anchor positions and offsets. To specify x/y offsets as well, this value - * may be specified as an Array of {@link Ext.Element#alignTo} method arguments. - *[ 'tl-bl?', [6,0] ]{@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, - deferEmptyText: false - }); - - this.mon(this.view, { - containerclick : this.onViewClick, - click : this.onViewClick, - scope :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
- ]
-});
-A {@link Ext.KeyNav KeyNav} object which handles navigation keys for this ComboBox. This performs actions - * based on keystrokes typed when the input field is focused.
- *After the ComboBox has been rendered, you may override existing navigation key functionality, - * or add your own based upon key names as specified in the {@link Ext.KeyNav KeyNav} class.
- *The function is executed in the scope (this reference of the ComboBox. Example:
-myCombo.keyNav.esc = function(e) { // Override ESC handling function
- this.collapse(); // Standard behaviour of Ext's ComboBox.
- this.setValue(this.startValue); // We reset to starting value on ESC
-};
-myCombo.keyNav.tab = function() { // Override TAB handling function
- this.onViewClick(false); // Select the currently highlighted row
-};
-