Combo

Widget

Enable caching of the last retrieved result until the timeout is reached.

Configure this either with:

• a number of minutes,
• a Duration object,
• a DurationConfig object, or
• a string parseable by parseDuration, e.g. 10m, 2 hours, etc.

This prevents unnecessary request roundtrips to the backend when reopening the picker and the filter has not been changed. The cache expiry timer is restarted on each outgoing request.

Falsy or unparseable values or negative numbers mean no caching.

A config object to configure the ChipView to display the selected value set when multiSelect is true.

For example the itemTpl or iconTpl might be configured to display richer chips for selected items.

If configured as true, this means that when an unmatched string is typed into the combo's input field, and Enter, or the multiValueSeparator is typed, a new record will be created using the typed string as the displayField.

If configured as a function, or the name of a function in the owning component hierarchy, the function will be called passing the string and combo field instance and should return the record to add (if any).

The new record will be appended to the store, and the value selected.

If the Store is an AjaxStore, the new record will be eiligible for syncing to the database through its createUrl.

If the AjaxStore is configured to autoCommit, the record will be synced immediately. If the server does not accept the new addition, the field is placed temporarily into an invalid state with a message that explains this.

For example:

    new Combo({
        label : 'Employee name',
        store : employees,
        createOnUnmatched(name, combo) {
            name = validateEmployeeName(name);

            if (name) {
                return new Employee({
                    name,
                    email : generateEmployeeEmail(name)
                });
            }
            else {
                combo.setError('Invalid new employee name');
            }
        }
    });

Template function that can be used to customize the displayed value

Text to display in the drop down when there are no items in the underlying store.

Defaults to use the noResults localization string ("No results" in En locale).

A function which creates an array of values for the filterParamName to pass any filters to the server upon load.

The default behaviour is just to set the parameter value to the filter's value, but the filter can be fully encoded for example:

   {
       encodeFilterParams(filters) {
           const result = [];

           for (const { property, operator, value, caseSensitive } of filters) {
               result.push(JSON.stringify({
                   field : property,
                   operator,
                   value,
                   caseSensitive
               }));
          }
       return result;
   }

The name of an operator type as implemented in operator to use when filtering the dropdown list based upon the typed value.

This defaults to 'startsWith', but the '*' operator may be used to match all values which contain the typed value.

Not used when filterParamName is set to cause remote dropdown loading. The exact filtering operation is up to the server.

Has a corresponding runtime filterOperator property.

Configure this as true to render the dropdown list as a permanently visible list in the document flow immediately below the input area instead of as a popup.

This also hides the expand trigger since it is not needed.

Rows to display in the dropdown (list items).

If an object, the property names provide the value for the Combo, and the property values provide the displayed test in the list and input area eg:

items : {
    small  : 'Small',
    medium : 'Medium',
    large  : 'Large'
}

If an array, each entry may be

• an object containing properties which must include the valueField and displayField which populates the dropdown with text and provides the corresponding field value.
• An array whose first value provides the value for the Combo and whose second value provides the displayed test in the list and input area.
• An array of values where the valueField and displayField are the same.

eg:

items : [
    {value : 'small',  text : 'Small'},
    {value : 'medium', text : 'Medium'},
    {value : 'large',  text : 'Large'},
]

or

items : [
    ['small',  'Small'],
    ['medium', 'Medium'],
    ['large',  'Large'],
]

or

items : [ 'Small', 'Medium', 'Large' ]

The delay in milliseconds to wait after the last keystroke before filtering the list.

This is a minimum of 300ms for remote filtering to keep network requests manageable, and defaults to 10ms for locally filtered stores.

Template string used to render the list items in the dropdown list

new Combo({
    listItemTpl : ({ text }) => `<div class="combo-color-box ${text}"></div>${text}`,
    editable    : false,
    items       : [
        'Black',
        'Green',
        'Orange',
        'Pink',
        'Purple',
        'Red',
        'Teal'
    ]
});

The minimum string length to trigger the filtering, only relevant when editable is true.

This defaults to 1 in the case of local filtering, but 4 if the filterParamName is set to cause remote dropdown loading.

Set to true to allow selection of multiple values from the dropdown list.

Each value is displayed as a "Chip" to the left of the input area. Chips may be selected using the ArrowLeft and ArrowRight arrow keys and deleted using the Delete key to remove values from the field. There is also a clickable close icon in each chip.

Use toggleAllIfCtrlPressed to implement "select all" behaviour.

{
    type   : 'combo',
    store  : myStore,
    picker : {
        toggleAllIfCtrlPressed : true
    }
}

Has a corresponding runtime multiSelect property.

Configuration object for the picker on initialization. Returns the picker instance at runtime.

For example:

new Combo({
    ...
    // configure the combobox picker
    picker : {
        listeners : {
            // prevent selection of item with id == 2
            beforeItem : ({ record }) => record.id !== 2
        }
    }
})

Has a corresponding runtime picker property.

Optionally a Filter config object which the combo should use for filtering using the typed value. This may use a filterBy property to test its value against any field in the passed record.

{
    type          : 'combo',
    store         : myStore,
    primaryFilter : {
        filterBy(record) {
            if (this.value == null) {
                return true;
            }
            const value = this.value.toLowerCase();

            // Match typed value with forename or surname
            return record.forename.toLowerCase().startsWith(value)
                || record.surname.toLowerCase().startsWith(value);
        }
    }
}

Field used for item value when populating from store. Setting this to null will yield the selected record as the Combo's value.

Leaving this value undefined means using the idField of the modelClass of the store as the value field.