Ext.ux.form.field.BoxSelect

The js is not minified so it is readable. See boxselect.js to view the code for these examples.

Ext.ux.form.field.BoxSelect extends Ext.form.field.ComboBox to provide a more 'multiSelect'-friendly control. The careful efforts made in this extension enable most (if not all) of the ComboBox examples to convert to BoxSelects easily. The examples included here showcase the differences between the default control and this extension.

Basic Configuration

All configuration values for ComboBox should work, but some defaults are changed:

multiSelect is defaulted to true.
Though single-select is supported, the primary use case for BoxSelect is multiSelect.
forceSelection is defaulted to true.
Most typical uses of multiple selections are from pre-formed lists, with some rare exceptions like multiple emails with auto-suggest.
typeAhead is still defaulted to false, but support for this feature has been added for multiSelect='true'. The basic combobox control does not support typeAhead in multiSelect configurations.
value can be used to initialize multiSelect values. The same formats of values are accepted for this as are accepted by calls to setValue.
- A string associated to the configured valueField
- When multiSelect is true, a string that is split using the field's delimiter
- An array of values associated to the configured valueField
- An array of records of the Model type associated to the field's store

Single Select

While the primary use case for BoxSelect is for multiple selection, single selection can also be set with multiSelect: false. If you want this to be the default case for all BoxSelect's, you can do so by adding the following before your BoxSelects are created:

Ext.ux.form.field.BoxSelect.prototype.multiSelect = false;

Automatic querying of remote stores for unknown values

If queryMode is set to 'remote', forceSelection is set to true, and a value is passed to the BoxSelect that is not in the store, a query will be sent to the store's configured proxy with a parameter with the name of the valueField, and a value of the unknown values separated by the configured delimiter. For example if the valueField is 'exampleIdField' and the delimiter is ', ' and unknown values '17' and '3281' are set, the following parameters will be passed to store.load():

{ exampleIdField: '17, 3281' }

This attempt to load the unknown values will be performed only once per initValue/setValue call. Any records that are still unknown after this request will be removed from the field's value, but all known values will be retained.

forceSelection: false -- Multiple Emails with Auto-suggest

The combo below illustrates the usage of 'forceSelection: false' with the BoxSelect component to enable the entry of multiple email addresses, with auto-suggestions provided from the attached store. New records are created using the user input for both the configured displayField and valueField. These new records are not added to the combo's store automatically.

There are three methods of determining when a new entry will be created:

When the user types the configured delimiter (defaults to ', '), the value that the user entered before the delimiter will be used to create a new record.
createNewOnEnter is defaulted to false. If set to true, a new entry will be created when the user presses Enter. This configuration option only applies if forceSelection is false.
createNewOnBlur is defaulted to false. If set to true, a new entry will be created when focus leaves the input field. This configuration option only applies if forceSelection is false, and is superceded by autoSelect and selectOnTab.

Other configuration options

The following configuration options are specific to the BoxSelect.

createNewOnEnter - please see the above forceSelection: false example.
createNewOnBlur - please see the above forceSelection: false example.
stacked is defaulted to false. If set to true, the labelled items will fill to the width of the list instead of being only as wide as the displayed value
pinList is defaulted to true. If set to false, the pick list will automatically collapse after a selection is made when multiSelect is true. This mimics the default behavior when multiSelect is false.
triggerOnClick is defaulted to true. If set to true, the pick list will emulate a trigger click when clicking in the field just like when a ComboBox is editable=false. Please see the above single select example for directions on globally overriding this default if desired.
grow is defaulted to true. If set to false, the list of selections will scroll when necessary, and the height of the field will not change. This setting has no effect if a fixed height is set for the field, either directly (e.g., through a height configuration), or by the containing layout.
growMin is defaulted to false. If grow is true, any numeric value will be used for the field's minimum height.
growMax is defaulted to false. If grow is true, any numeric value will be used for the field's maximum height and the list of selections will scroll when necessary.

Value setting and events

The following shows examples of manually managing the values of the field and displays the value-based events. Except where noted, the mixedValue parameters can be specified in any of the forms listed in the Basic Configuration examples above. In general, getRawValue and setRawValue should not be used, as of ExtJS 4 they are formally for the rendered field output only.