Ext.ux.form.field.BoxSelect Examples and Reference
The examples below contain buttons to show their individual configurations inline. Additionally, 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, provide general information about advanced usage
of BoxSelect, and are used as test cases when resolving reported issues and developing new functionality.
Table of Contents
Templates
Back to table of contents
Display of the selected values and the dropdowns are both configurable via templates.
- labelTpl controls the display of selected values within the textfield box.
- listConfig part of the standard ComboBox control, controls the display of values
within the dropdown pick list.
Single Select
Back to table of contents
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;
Unknown Value Handling with Remote Stores
Back to table of contents
Please note: the example page hosted on the github pages do not allow execution of php scripts,
so this example will not work there. This example requires hosting on a server that allows php script execution as it
is meant to demonstrate more complex interactions with a remote server.
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 'abbr' and the delimiter is '|' and unknown values 'NC', 'VA' and 'ZZ' are set, the following parameters
will be passed to store.load():
{ abbr: 'NC|VA|ZZ' }
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. In the above example,
the 'ZZ' entry was discarded.
A php script (states.php) is included in the example source for a basic implementation of a server side script.
Multiple Emails with Auto-suggest
Back to table of contents
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 four 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.
-
When a user pastes in to the field, the value will be split according to the configured
delimiter (defaults to ', '),
and any values entered will be parsed in to new/existing records.
-
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
Back to table of contents
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.
- filterPickList is defaulted to false. If set to true, currently selected values will
be hidden from the expanded pick list. This is done via css to maintain simplicity of store
and filter management and consistency for both local and remote querying.
Value Setting and Events
Back to table of contents
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.