Package com.smartgwt.client.widgets.form.fields

Class SetFilterItem

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.core.RefDataClass
com.smartgwt.client.data.Field
com.smartgwt.client.widgets.form.fields.FormItem
com.smartgwt.client.widgets.form.fields.StaticTextItem
com.smartgwt.client.widgets.form.fields.MultiPickerItem
com.smartgwt.client.widgets.form.fields.SetFilterItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasShowContextMenuHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers
public class SetFilterItem extends MultiPickerItem
Specialized MultiPickerItem used for generating search criteria in the FilterEditor and in SearchForms.

SetFilterItem generates inSet and notInSet filter criteria from a set of possible values, which can be provided via an explicit valueMap or optionDataSource, or can be derived from the target databound component or a list of records.

In particular, when attached to a databound component such as a ListGrid, SetFilterItem can provide "Excel-style filtering", allowing the user to pick from amongst whatever values are present in the dataset.

For large datasets, SetFilterItem will also intelligently use locally cached data when possible, deriving its set of options from loaded data without the need for an extra dataSource fetch. Specifically, when all matching records are loaded in the filterTargetComponent, the options are derived from already loaded data. If the set of data is incomplete (due to data paging), the SetFilterItem will derive options from its optionDataSource.

Note that deriveUniqueValues defaults to true for setFilterItems.

When a SetFilterItem is used as a ListGrid filterEditor, the filterTargetComponent will automatically be set to the grid being filtered.

The item's picker-component can be customized via settings such as sortField, or by configuring auto-children like the search-form, the main pickList-grid or the separate list of selected values. You can use MultiPickerItem.optionFilterContext to apply custom requestProperties to fetches from the main pickList grid.

  • Constructor Details

    • SetFilterItem

      public SetFilterItem()

    • SetFilterItem

      public SetFilterItem(JavaScriptObject jsObj)

    • SetFilterItem

      public SetFilterItem(String name)

  • Method Details

    • getOrCreateRef

      public static SetFilterItem getOrCreateRef(JavaScriptObject jsObj)

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changePickerIconDefaults

      public static void changePickerIconDefaults(FormItemIcon defaults)

    • setCanExpand

      public SetFilterItem setCanExpand(Boolean canExpand)
      Should we show an MultiPickerItem.expansionIcon expand button allowing the user to show an expanded view of the MultiPickerItem.pickList with multiple fields.

      canExpand only applies to MultiPickerItems with selectionStyle set to "pickList" or "pickTree" and an explicitly specified set of MultiPickerItem.expandedPickListFields to display within the expanded view.

      Overrides:
      setCanExpand in class MultiPickerItem
      Parameters:
      canExpand - New canExpand value. Default value is false
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getCanExpand

      public Boolean getCanExpand()
      Should we show an MultiPickerItem.expansionIcon expand button allowing the user to show an expanded view of the MultiPickerItem.pickList with multiple fields.

      canExpand only applies to MultiPickerItems with selectionStyle set to "pickList" or "pickTree" and an explicitly specified set of MultiPickerItem.expandedPickListFields to display within the expanded view.

      Overrides:
      getCanExpand in class MultiPickerItem
      Returns:
      Current canExpand value. Default value is false

    • setDefaultUseUnselectedValues

      public SetFilterItem setDefaultUseUnselectedValues(Boolean defaultUseUnselectedValues)
      Should this item track unselected or selected values by default?

      If toggleUseUnselectedValuesOnSelectAll, for setFilterItems with no current criteria (I.E. no explicitly selected or unselected values), this property will be evaluated when the pickList is shown and useUnselectedValues will be set to match this value. This causes the options in the pickList to always show up checked (or unchecked) by default, matching user expectations of what an "empty" filter represents.

      May be set to null, in which case useUnselectedValues will not be modified when the pickList is shown for an empty SetFilterItem

      Note : This is an advanced setting

      Parameters:
      defaultUseUnselectedValues - New defaultUseUnselectedValues value. Default value is true
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getDefaultUseUnselectedValues

      public Boolean getDefaultUseUnselectedValues()
      Should this item track unselected or selected values by default?

      If toggleUseUnselectedValuesOnSelectAll, for setFilterItems with no current criteria (I.E. no explicitly selected or unselected values), this property will be evaluated when the pickList is shown and useUnselectedValues will be set to match this value. This causes the options in the pickList to always show up checked (or unchecked) by default, matching user expectations of what an "empty" filter represents.

      May be set to null, in which case useUnselectedValues will not be modified when the pickList is shown for an empty SetFilterItem

      Returns:
      Current defaultUseUnselectedValues value. Default value is true

    • setDeriveUniqueValues

      public SetFilterItem setDeriveUniqueValues(Boolean deriveUniqueValues)
      If this MultiPickerItem is deriving its options from a dataSource, should it ensure unique field values by grouping by the value field for this item? This is not necessary if the target dataSource value field is already unique - for example if this is the primaryKey field for a dataSource.

      Note that for MultiPickerItems with deriveUniqueValues:true, any expandedPickListFields to be displayed in the expanded view will not be able to display meaningful values unless a summaryFunction is supplied to produce aggregated values from the grouped data. This may be achieved by specifying summaryFunctions directly on the optionFilterContext, or on the operationBinding for the fetch operation.

      Note : This is an advanced setting

      Overrides:
      setDeriveUniqueValues in class MultiPickerItem
      Parameters:
      deriveUniqueValues - New deriveUniqueValues value. Default value is true
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getDeriveUniqueValues

      public Boolean getDeriveUniqueValues()
      If this MultiPickerItem is deriving its options from a dataSource, should it ensure unique field values by grouping by the value field for this item? This is not necessary if the target dataSource value field is already unique - for example if this is the primaryKey field for a dataSource.

      Note that for MultiPickerItems with deriveUniqueValues:true, any expandedPickListFields to be displayed in the expanded view will not be able to display meaningful values unless a summaryFunction is supplied to produce aggregated values from the grouped data. This may be achieved by specifying summaryFunctions directly on the optionFilterContext, or on the operationBinding for the fetch operation.

      Overrides:
      getDeriveUniqueValues in class MultiPickerItem
      Returns:
      Current deriveUniqueValues value. Default value is true

    • setExpandedPickListFields

      public SetFilterItem setExpandedPickListFields(ListGridField... expandedPickListFields)
      If canExpand is true, this is the list of fields to display in the PickList or pickTree when the picker is expanded
      Overrides:
      setExpandedPickListFields in class MultiPickerItem
      Parameters:
      expandedPickListFields - New expandedPickListFields value. Default value is null
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getExpandedPickListFields

      public ListGridField[] getExpandedPickListFields()
      If canExpand is true, this is the list of fields to display in the PickList or pickTree when the picker is expanded
      Overrides:
      getExpandedPickListFields in class MultiPickerItem
      Returns:
      Current expandedPickListFields value. Default value is null

    • setFilterTargetComponent

      public SetFilterItem setFilterTargetComponent(DataBoundComponent filterTargetComponent)
      Target component for which this SetFilterItem is generating criteria. By default the sourceList will be the data object for the target component, and the option dataSource, option criteria, option fetch operation and so on will be derived from the target component's configuration.

      For a setFilterItem embedded in a filter editor, this will be the target listGrid.

      Parameters:
      filterTargetComponent - New filterTargetComponent value. Default value is null
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getFilterTargetComponent

      public DataBoundComponent getFilterTargetComponent()
      Target component for which this SetFilterItem is generating criteria. By default the sourceList will be the data object for the target component, and the option dataSource, option criteria, option fetch operation and so on will be derived from the target component's configuration.

      For a setFilterItem embedded in a filter editor, this will be the target listGrid.

      Returns:
      Current filterTargetComponent value. Default value is null

    • setSelectedOperator

      public SetFilterItem setSelectedOperator(OperatorId selectedOperator)
      Operator for the criteria generated by this item when useUnselectedValues is false.

      Note : This is an advanced setting

      Parameters:
      selectedOperator - New selectedOperator value. Default value is "inSet"
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getSelectedOperator

      public OperatorId getSelectedOperator()
      Operator for the criteria generated by this item when useUnselectedValues is false.
      Returns:
      Current selectedOperator value. Default value is "inSet"

    • setSelectionStyle

      public SetFilterItem setSelectionStyle(MultiPickerSelectionStyle selectionStyle)
      selectionStyle:"shuttle" is not supported for SetFilterItem
      Overrides:
      setSelectionStyle in class MultiPickerItem
      Parameters:
      selectionStyle - New selectionStyle value. Default value is "pickList"
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getSelectionStyle

      public MultiPickerSelectionStyle getSelectionStyle()
      selectionStyle:"shuttle" is not supported for SetFilterItem
      Overrides:
      getSelectionStyle in class MultiPickerItem
      Returns:
      Current selectionStyle value. Default value is "pickList"

    • setToggleUseUnselectedValuesOnSelectAll

      public SetFilterItem setToggleUseUnselectedValuesOnSelectAll(Boolean toggleUseUnselectedValuesOnSelectAll)
      Should this item toggle between tracking selected options and using them to generate "inSet" criteria and unselected options and using them to generate "notInSet" criteria when the user clicks the MultiPickerItem.selectAllButton and MultiPickerItem.deselectAllButton on an unfiltered list of options.

      See useUnselectedValues for more detail

      Note : This is an advanced setting

      Parameters:
      toggleUseUnselectedValuesOnSelectAll - New toggleUseUnselectedValuesOnSelectAll value. Default value is true
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getToggleUseUnselectedValuesOnSelectAll

      public Boolean getToggleUseUnselectedValuesOnSelectAll()
      Should this item toggle between tracking selected options and using them to generate "inSet" criteria and unselected options and using them to generate "notInSet" criteria when the user clicks the MultiPickerItem.selectAllButton and MultiPickerItem.deselectAllButton on an unfiltered list of options.

      See useUnselectedValues for more detail

      Returns:
      Current toggleUseUnselectedValuesOnSelectAll value. Default value is true

    • setUnselectedOperator

      public SetFilterItem setUnselectedOperator(OperatorId unselectedOperator)
      Operator for the criteria generated by this item when useUnselectedValues is true.

      Note : This is an advanced setting

      Parameters:
      unselectedOperator - New unselectedOperator value. Default value is "notInSet"
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getUnselectedOperator

      public OperatorId getUnselectedOperator()
      Operator for the criteria generated by this item when useUnselectedValues is true.
      Returns:
      Current unselectedOperator value. Default value is "notInSet"

    • setUseUnselectedValues

      public SetFilterItem setUseUnselectedValues(Boolean useUnselectedValues)
      The SetFilterItem has the capability to treat its set of options as selected by default, and explicitly track the options a user has unselected, or treat them as unselected by default and explicitly track the user-selected objects. This attribute denotes whether the item is currently tracking explicitly selected or unselected values.

      While tracking selected values, this item will generate inSet criteria. While tracking unselected values, it will generate notInSet criteria.

      If toggleUseUnselectedValuesOnSelectAll is true, if the current set of options is unfiltered, the MultiPickerItem.selectAllButton and MultiPickerItem.deselectAllButton will clear any current value and toggle useUnselectedValues - effectively switching between tracking inclusive (inSet) values and exclusive (notInSet) values.

      If this method is called after the component has been drawn/initialized: Clear any current value for this item and dynamically update useUnselectedValues.

      Parameters:
      useUnselectedValues - new value for useUnselectedValues. Default value is true
      Returns:
      SetFilterItem instance, for chaining setter calls

    • getUseUnselectedValues

      public Boolean getUseUnselectedValues()
      The SetFilterItem has the capability to treat its set of options as selected by default, and explicitly track the options a user has unselected, or treat them as unselected by default and explicitly track the user-selected objects. This attribute denotes whether the item is currently tracking explicitly selected or unselected values.

      While tracking selected values, this item will generate inSet criteria. While tracking unselected values, it will generate notInSet criteria.

      If toggleUseUnselectedValuesOnSelectAll is true, if the current set of options is unfiltered, the MultiPickerItem.selectAllButton and MultiPickerItem.deselectAllButton will clear any current value and toggle useUnselectedValues - effectively switching between tracking inclusive (inSet) values and exclusive (notInSet) values.

      Returns:
      Current useUnselectedValues value. Default value is true

    • setDefaultProperties

      public static void setDefaultProperties(SetFilterItem setFilterItemProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      setFilterItemProperties - properties that should be used as new defaults when instances of this class are created
      See Also: