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.