Class Ext.ux.form.SelectBox

Note: this config is only used when this Component is rendered by a Container which has been configured to use an AnchorLayout based layout manager, for example:

See Ext.layout.AnchorLayout.anchor also.

Specify the id of the element, a DOM element or an existing Element corresponding to a DIV that is already present in the document that specifies some structural markup for this component.

A DomHelper element spec, or true for a default element spec. Used to create the Element which will encapsulate this Component. See autoEl for details. Defaults to:

{tag: "input", type: "text", size: "24", autocomplete: "off"}

A tag name or DomHelper spec used to create the Element which will encapsulate this Component.

You do not normally need to specify this. For the base classes Ext.Component, Ext.BoxComponent, and Ext.Container, this defaults to 'div'. The more complex Ext classes use a more complex DOM structure created by their own onRender methods.

This is intended to allow the developer to create application-specific utility Components encapsulated by different DOM elements. Example usage:

{
    xtype: 'box',
    autoEl: {
        tag: 'img',
        src: 'http://www.example.com/example.jpg'
    }
}, {
    xtype: 'box',
    autoEl: {
        tag: 'blockquote',
        html: 'autoEl is cool!'
    }
}, {
    xtype: 'container',
    autoEl: 'ul',
    cls: 'ux-unordered-list',
    items: {
        xtype: 'box',
        autoEl: 'li',
        html: 'First list item'
    }
}

True to use height:'auto', false to use fixed height (or allow it to be managed by its parent Container's layout manager. Defaults to false.

Note: Although many components inherit this config option, not all will function as expected with a height of 'auto'. Setting autoHeight:true means that the browser will manage height based on the element's contents, and that Ext will not manage it at all.

If the browser is managing the height, be aware that resizes performed by the browser in response to changes within the structure of the Component cannot be detected. Therefore changes to the height might result in elements needing to be synchronized with the new height. Example:

var w = new Ext.Window({
    title: 'Window',
    width: 600,
    autoHeight: true,
    items: {
        title: 'Collapse Me',
        height: 400,
        collapsible: true,
        border: false,
        listeners: {
            beforecollapse: function() {
                w.el.shadow.hide();
            },
            beforeexpand: function() {
                w.el.shadow.hide();
            },
            collapse: function() {
                w.syncShadow();
            },
            expand: function() {
                w.syncShadow();
            }
        }
    }
}).show();

True to use width:'auto', false to use fixed width (or allow it to be managed by its parent Container's layout manager. Defaults to false.

Note: Although many components inherit this config option, not all will function as expected with a width of 'auto'. Setting autoWidth:true means that the browser will manage width based on the element's contents, and that Ext will not manage it at all.

If the browser is managing the width, be aware that resizes performed by the browser in response to changes within the structure of the Component cannot be detected. Therefore changes to the width might result in elements needing to be synchronized with the new width. For example, where the target element is:

<div id='grid-container' style='margin-left:25%;width:50%'></div>

var myPanel = new Ext.Panel({
    renderTo: 'grid-container',
    monitorResize: true, // relay on browser resize
    title: 'Panel',
    height: 400,
    autoWidth: true,
    layout: 'hbox',
    layoutConfig: {
        align: 'stretch'
    },
    defaults: {
        flex: 1
    },
    items: [{
        title: 'Box 1',
    }, {
        title: 'Box 2'
    }, {
        title: 'Box 3'
    }],
});

The CSS class used to to apply to the special clearing div rendered directly after each form field wrapper to provide field clearing (defaults to 'x-form-clear-left').

Note: this config is only used when this Component is rendered by a Container which has been configured to use the FormLayout layout manager (e.g. Ext.form.FormPanel or specifying layout:'form') and either a fieldLabel is specified or isFormField=true is specified.

See Ext.layout.FormLayout.fieldTpl also.

An optional extra CSS class that will be added to this component's container. This can be useful for adding customized styles to the container or any of its children using standard CSS rules. See Ext.layout.ContainerLayout.extraCls also.

Note: ctCls defaults to '' except for the following class which assigns a value by default:

ctCls: 'x-box-layout-ct custom-class'

Be aware that conformant with the HTML specification, disabled Fields will not be submitted.

See also valueField.

Note: if using a ComboBox in an Editor Grid a renderer will be needed to show the displayField when the editor is not active.

The label text to display next to this Component (defaults to '').

Note: this config is only used when this Component is rendered by a Container which has been configured to use the FormLayout layout manager (e.g. Ext.form.FormPanel or specifying layout:'form').

Also see hideLabel and Ext.layout.FormLayout.fieldTpl.

new Ext.FormPanel({
    height: 100,
    renderTo: Ext.getBody(),
    items: [{
        xtype: 'textfield',
        fieldLabel: 'Name'
    }]
});

Note: the hidden field's id will also default to this name if hiddenId is not specified. The ComboBox id and the hiddenId should be different, since no two DOM nodes should share the same id. So, if the ComboBox name and hiddenName are the same, you should specify a unique hiddenId.

true to completely hide the label element (label and separator). Defaults to false. By default, even if you do not specify a fieldLabel the space will still be reserved so that the field will line up with other fields that do have labels. Setting this to true will cause the field to not reserve that space.

Note: see the note for clearCls.

new Ext.FormPanel({
    height: 100,
    renderTo: Ext.getBody(),
    items: [{
        xtype: 'textfield'
        hideLabel: true
    }]
});

How this component should be hidden. Supported values are 'visibility' (css visibility), 'offsets' (negative offset position) and 'display' (css display).

Note: the default of 'display' is generally preferred since items are automatically laid out when they are first shown (no sizing is done while hidden).

The unique id of this component (defaults to an auto-assigned id). You should assign an id if you need to be able to access the component later and you do not have an object reference available (e.g., using Ext.getCmp).

Note that this id will also be used as the element id for the containing HTML element that is rendered to the page for this component. This allows you to write id-based CSS rules to style the specific instance of this component uniquely, and also to select sub-elements using this component's id as the parent.

Note: to avoid complications imposed by a unique id also see itemId and ref.

Note: to access the container of an item see ownerCt.

An additional CSS class to apply to the div wrapping the form item element of this field. If supplied, itemCls at the field level will override the default itemCls supplied at the container level. The value specified for itemCls will be added to the default class ('x-form-item').

Since it is applied to the item wrapper (see Ext.layout.FormLayout.fieldTpl), it allows you to write standard CSS rules that can apply to the field, the label (if specified), or any other element within the markup for the field.

Note: see the note for fieldLabel.

// Apply a style to the field's label:
<style>
    .required .x-form-item-label {font-weight:bold;color:red;}
</style>

new Ext.FormPanel({
	height: 100,
	renderTo: Ext.getBody(),
	items: [{
		xtype: 'textfield',
		fieldLabel: 'Name',
		itemCls: 'required' //this label will be styled
	},{
		xtype: 'textfield',
		fieldLabel: 'Favorite Color'
	}]
});

An itemId can be used as an alternative way to get a reference to a component when no object reference is available. Instead of using an id with Ext.getCmp, use itemId with Ext.Container.getComponent which will retrieve itemId's or id's. Since itemId's are an index to the container's internal MixedCollection, the itemId is scoped locally to the container -- avoiding potential conflicts with Ext.ComponentMgr which requires a unique id.

var c = new Ext.Panel({ //
    height: 300,
    renderTo: document.body,
    layout: 'auto',
    items: [
        {
            itemId: 'p1',
            title: 'Panel 1',
            height: 150
        },
        {
            itemId: 'p2',
            title: 'Panel 2',
            height: 150
        }
    ]
})
p1 = c.getComponent('p1'); // not the same as Ext.getCmp()
p2 = p1.ownerCt.getComponent('p2'); // reference via a sibling

Also see id and ref.

Note: to access the container of an item see ownerCt.

A simple CSS selector (e.g. div.some-class or span:first-child) that will be used to determine what nodes the Ext.DataView which handles the dropdown display will be working with.

Note: this setting is required if a custom XTemplate has been specified in tpl which assigns a class other than

'x-combo-list-item'

The separator to display after the text of each fieldLabel. This property may be configured at various levels. The order of precedence is:

Note: see the note for clearCls.

Also see hideLabel and Ext.layout.FormLayout.fieldTpl.

new Ext.FormPanel({
    height: 100,
    renderTo: Ext.getBody(),
    layoutConfig: {
        labelSeparator: '~'   // layout config has lowest priority (defaults to ':')
    },
    labelSeparator: '>>',     // config at container level
    items: [{
        xtype: 'textfield',
        fieldLabel: 'Field 1',
        labelSeparator: '...' // field/component level config supersedes others
    },{
        xtype: 'textfield',
        fieldLabel: 'Field 2' // labelSeparator will be '='
    }]
});

A CSS style specification string to apply directly to this field's label. Defaults to the container's labelStyle value if set (e.g., Ext.layout.FormLayout.labelStyle , or '').

Note: see the note for clearCls.

Also see hideLabel and Ext.layout.FormLayout.fieldTpl.

new Ext.FormPanel({
    height: 100,
    renderTo: Ext.getBody(),
    items: [{
        xtype: 'textfield',
        fieldLabel: 'Name',
        labelStyle: 'font-weight:bold;'
    }]
});

A config object containing one or more event handlers to be added to this object during initialization. This should be a valid listeners config object as specified in the addListener example for attaching multiple handlers at once.

DOM events from ExtJs Components

While some ExtJs Component classes export selected DOM events (e.g. "click", "mouseover" etc), this is usually only done when extra value can be added. For example the DataView's click event passing the node clicked on. To access DOM events directly from a Component's HTMLElement, listeners must be added to the Element after the Component has been rendered. A plugin can simplify this step:

// Plugin is configured with a listeners config object.
// The Component is appended to the argument list of all handler functions.
Ext.DomObserver = Ext.extend(Object, {
    constructor: function(config) {
        this.listeners = config.listeners ? config.listeners : config;
    },

    // Component passes itself into plugin's init method
    init: function(c) {
        var p, l = this.listeners;
        for (p in l) {
            if (Ext.isFunction(l[p])) {
                l[p] = this.createHandler(l[p], c);
            } else {
                l[p].fn = this.createHandler(l[p].fn, c);
            }
        }

        // Add the listeners to the Element immediately following the render call
        c.render = c.render.createSequence(function() {
            var e = c.getEl();
            if (e) {
                e.on(l);
            }
        });
    },

    createHandler: function(fn, c) {
        return function(e) {
            fn.call(this, e, c);
        };
    }
});

var combo = new Ext.form.ComboBox({

    // Collapse combo when its element is clicked on
    plugins: [ new Ext.DomObserver({
        click: function(evt, comp) {
            comp.collapse();
        }
    })],
    store: myStore,
    typeAhead: true,
    mode: 'local',
    triggerAction: 'all'
});

Note: this config is only used when this BoxComponent is rendered by a Container which has been configured to use the BorderLayout or one of the two BoxLayout subclasses.

An object containing margins to apply to this BoxComponent in the format:

{
    top: (top margin),
    right: (right margin),
    bottom: (bottom margin),
    left: (left margin)
}

May also be a string containing space-separated, numeric margin values. The order of the sides associated with each value matches the way CSS processes margin values:

Defaults to:

{top:0, right:0, bottom:0, left:0}

var myField = new Ext.form.NumberField({
    id: 'mobile',
    anchor:'90%',
    fieldLabel: 'Mobile',
    maxLength: 16, // for validation
    autoCreate: {tag: 'input', type: 'text', size: '20', autocomplete: 'off', maxlength: '10'}
});

Value         Description
-----------   ----------------------------------------------------------------------
qtip          Display a quick tip when the user hovers over the field
title         Display a default browser title attribute popup
under         Add a block div beneath the field containing the error text
side          Add an error icon to the right of the field with a popup on hover
[element id]  Add the error text directly to the innerHTML of the specified element

Note: this only sets the element's readOnly DOM attribute. Setting readOnly=true, for example, will not disable triggering a ComboBox or DateField; it gives you the option of forcing the user to choose via the trigger without typing in the text box. To hide the trigger use hideTrigger.

A path specification, relative to the Component's ownerCt specifying into which ancestor Container to place a named reference to this Component.

The ancestor axis can be traversed by using '/' characters in the path. For example, to put a reference to a Toolbar Button into the Panel which owns the Toolbar:

var myGrid = new Ext.grid.EditorGridPanel({
    title: 'My EditorGridPanel',
    store: myStore,
    colModel: myColModel,
    tbar: [{
        text: 'Save',
        handler: saveChanges,
        disabled: true,
        ref: '../saveButton'
    }],
    listeners: {
        afteredit: function() {
//          The button reference is in the GridPanel
            myGrid.saveButton.enable();
        }
    }
});

In the code above, if the ref had been 'saveButton' the reference would have been placed into the Toolbar. Each '/' in the ref moves up one level from the Component's ownerCt.

Note: this config is only used when this BoxComponent is rendered by a Container which has been configured to use the BorderLayout layout manager (e.g. specifying layout:'border').

See Ext.layout.BorderLayout also.

Specify the id of the element, a DOM element or an existing Element that this component will be rendered into.

See render also.

An array of events that, when fired, should trigger this component to save its state (defaults to none). stateEvents may be any type of event supported by this component, including browser or custom events (e.g., ['click', 'customerchange']).

See stateful for an explanation of saving and restoring Component state.

See stateful for an explanation of saving and restoring Component state.

A flag which causes the Component to attempt to restore the state of internal properties from a saved state on startup. The component must have either a stateId or id assigned for state to be managed. Auto-generated ids are not guaranteed to be stable across page loads and cannot be relied upon to save and restore the same state for a component.

For state saving to work, the state manager's provider must have been set to an implementation of Ext.state.Provider which overrides the set and get methods to save and recall name/value pairs. A built-in implementation, Ext.state.CookieProvider is available.

To set the state provider for the current page:

Ext.state.Manager.setProvider(new Ext.state.CookieProvider({
    expires: new Date(new Date().getTime()+(1000*60*60*24*7)), //7 days from now
}));

A stateful Component attempts to save state when one of the events listed in the stateEvents configuration fires.

To save state, a stateful Component first serializes its state by calling getState. By default, this function does nothing. The developer must provide an implementation which returns an object hash which represents the Component's restorable state.

The value yielded by getState is passed to Ext.state.Manager.set which uses the configured Ext.state.Provider to save the object keyed by the Component's stateId, or, if that is not specified, its id.

During construction, a stateful Component attempts to restore its state by calling Ext.state.Manager.get passing the stateId, or, if that is not specified, the id.

The resulting object is passed to applyState. The default implementation of applyState simply copies properties into the object, but a developer may override this to support more behaviour.

You can perform extra processing on state save and restore by attaching handlers to the beforestaterestore, staterestore, beforestatesave and statesave events.

See also mode.

new Ext.Panel({
    title: 'Some Title',
    renderTo: Ext.getBody(),
    width: 400, height: 300,
    layout: 'form',
    items: [{
        xtype: 'textarea',
        style: {
            width: '95%',
            marginBottom: '10px'
        }
    },
        new Ext.Button({
            text: 'Send',
            minWidth: '100',
            style: {
                marginBottom: '10px'
            }
        })
    ]
});

The template string, or Ext.XTemplate instance to use to display each item in the dropdown list. The dropdown list is displayed in a DataView. See 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 Store. In the example above an

ext:qtip

To preserve the default visual look of list items, add the CSS class name

x-combo-list-item

Also see itemSelector for additional details.

See also queryParam.

A DomHelper config object specifying the structure of the trigger element for this Field. (Optional).

Specify this when you need a customized element to act as the trigger button for a TriggerField.

Note that when using this option, it is the developer's responsibility to ensure correct sizing, positioning and appearance of the trigger. Defaults to:

{tag: "img", src: Ext.BLANK_IMAGE_URL, cls: "x-form-trigger " + this.triggerClass}

Note: use of a valueField requires the user to make a selection in order for a value to be mapped. See also hiddenName, hiddenValue, and displayField.