Package com.smartgwt.client.docs

# Interface ComboBoxFiltering

public interface ComboBoxFiltering

### ComboBoxItem PickList Filtering

The criteria used to decide which options should appear in the drop-down PickList shown by a ComboBox are determined as follows.

While the user is typing in a value, the `ComboBoxItem.getPickListFilterCriteria()` method will return the typed-in value as part of the criteria, so that only matching values are shown. Matching is determined by the `textMatchStyle`. Note that the `ComboBoxItem.filterFields` attribute may be used to determine which fields filtering is performed against for databound comboBoxItems.

If the user explicitly shows the down-down pickList, via either clicking on the drop down icon or using the Ctrl+Arrow Down key combination, the typed-in value is ignored for filtering.

If included in the criteria, the typed-in value will be included as a value for the `displayField` (or for the `valueField` if `this.displayField` is unspecified).

Static criteria, specified via `optionCriteria` or `pickListCriteria`, will always be included by the default implementation (combined with the typed in value if appropriate).

For custom pick list filter criteria, we recommend calling the `com.smartgwt.client.widgets.form.fields.ComboBoxItem.setPickListFilterCriteriaFunction` method. If you are implementing your own pickList filter criteria, the read-only property `this.filterWithValue` can be read to determine whether the ComboBox would ordinarily ignore the typed-in value for filtering. Note that in addition to cases where the user explicitly shows the pickList, `filterWithValue` will also be `true` during a call to `ComboBoxItem.fetchData()` on a databound comboBox.

NOTE: The defaut implementation of this method will return an `AdvancedCriteria` object if multiple `ComboBoxItem.filterFields` are specified, or if there are field collisions between any specified static `optionCriteria`, `pickListCriteria` and the entered value. AdvancedCriteria are not supported by all DataSource types, including the built-in server-side SQL dataSources in Smart GWT Pro edition (though they are supported by SQL dataSources in Power and Enterprise editions).

Client-Side Filtering
By default, the ComboBoxItem will automatically use client-side filtering whenever it receives a complete set of results for a given search string, and then the user types more letters (so reducing the results further).

Client-side filtering may malfunction if the server filtering behavior can't be replicated client-side (for example, Google Search). To disable client-side filtering so that the comboBox always contacts the server for data whenever the use changes the search string, set `ComboBoxItem.useClientFiltering` to false.

However, disabling client-side filtering will slow down the UI and cause more round-trips to the server, so if client-side filtering is malfunctioning but should work, try to correct the problem rather than disable the feature.

For example, if the initial search works correctly but adding more letters always causes zero matches, most likely the Records returned by the server lack values for the field(s) targeted by the filter criteria, or the field values returned by the server don't match the criteria values.

View the returned data in the RPC tab in the Developer Console and enable the "ResultSet" log category in the "Results" tab to troubleshoot how the filter criteria are being applied to data, and look closely at your settings for `valueField` and `displayField`.