Package com.smartgwt.client.widgets.form

Class FilterBuilder

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.smartgwt.client.widgets.BaseWidget
com.smartgwt.client.widgets.Canvas
com.smartgwt.client.widgets.layout.Layout
com.smartgwt.client.widgets.form.FilterBuilder
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget, LogicalStructure, HasClearHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragMoveHandlers, HasDragRepositionMoveHandlers, HasDragRepositionStartHandlers, HasDragRepositionStopHandlers, HasDragResizeMoveHandlers, HasDragResizeStartHandlers, HasDragResizeStopHandlers, HasDragStartHandlers, HasDragStopHandlers, HasDropHandlers, HasDropMoveHandlers, HasDropOutHandlers, HasDropOverHandlers, HasFocusChangedHandlers, HasHoverHandlers, HasHoverHiddenHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseStillDownHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasMovedHandlers, HasParentMovedHandlers, HasResizedHandlers, HasRightMouseDownHandlers, HasRuleContextChangedHandlers, HasScrolledHandlers, HasShowContextMenuHandlers, HasVisibilityChangedHandlers, HasFilterChangedHandlers, HasSearchHandlers, HasMembersChangedHandlers
public class FilterBuilder extends Layout implements HasFilterChangedHandlers, HasSearchHandlers
A form that allows the user to input advanced search criteria, including operators on field values such as "less than", and sub-clauses using "AND" and "OR" operators.

A FilterBuilder produces an AdvancedCriteria object, which the DataSource subsystem can use to filter datasets, including the ability to perform such filtering within the browser for datasets that are completely loaded.

The operators available for each field can be customized at the DataSource level via DataSourceField.validOperators, DataSource.setTypeOperators() and related APIs.

  • Constructor Details

    • FilterBuilder

      public FilterBuilder()

    • FilterBuilder

      public FilterBuilder(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static FilterBuilder 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:

    • create

      protected JavaScriptObject create()
      Overrides:
      create in class Layout

    • getAddButton

      public ImgButton getAddButton() throws IllegalStateException
      An ImgButton that allows new clauses to be added if showAddButton is set.

      This component is an AutoChild named "addButton". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current addButton value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setAddButtonPrompt

      public FilterBuilder setAddButtonPrompt(String addButtonPrompt) throws IllegalStateException
      The hover prompt text for the add button.
      Parameters:
      addButtonPrompt - New addButtonPrompt value. Default value is "Add"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAddButtonPrompt

      public String getAddButtonPrompt()
      The hover prompt text for the add button.
      Returns:
      Current addButtonPrompt value. Default value is "Add"

    • setAggregationDataSources

      public FilterBuilder setAggregationDataSources(DataSource... aggregationDataSources) throws IllegalStateException
      List of DataSources to choose from when constructing a field or value sub-query if allowAggregates is enabled. If not specified, the filter DataSource plus all related DataSources are used.
      Parameters:
      aggregationDataSources - New aggregationDataSources value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAggregationDataSources

      public DataSource[] getAggregationDataSources()
      List of DataSources to choose from when constructing a field or value sub-query if allowAggregates is enabled. If not specified, the filter DataSource plus all related DataSources are used.
      Returns:
      Current aggregationDataSources value. Default value is null

    • setAllowAggregates

      public FilterBuilder setAllowAggregates(Boolean allowAggregates) throws IllegalStateException
      Should aggregates be allowed as either the field or value?

      This feature is available with Power or better licenses only. See smartclient.com/product for details.

      Parameters:
      allowAggregates - New allowAggregates value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getAllowAggregates

      public Boolean getAllowAggregates()
      Should aggregates be allowed as either the field or value?

      This feature is available with Power or better licenses only. See smartclient.com/product for details.

      Returns:
      Current allowAggregates value. Default value is null
      See Also:

    • setAllowedFields

      public FilterBuilder setAllowedFields(String... allowedFields) throws IllegalStateException
      List of explicit fields for user field selection. If not specified, the list of fields is derived from the dataSource.

      Note: this property is not a security feature as it only controls the UI. To consistently limit searchability for certain fields use canFilter.

      Parameters:
      allowedFields - New allowedFields value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getAllowedFields

      public String[] getAllowedFields()
      List of explicit fields for user field selection. If not specified, the list of fields is derived from the dataSource.

      Note: this property is not a security feature as it only controls the UI. To consistently limit searchability for certain fields use canFilter.

      Returns:
      Current allowedFields value. Default value is null
      See Also:

    • setAllowEmpty

      public FilterBuilder setAllowEmpty(Boolean allowEmpty) throws IllegalStateException
      If set to false, the last clause cannot be removed.
      Parameters:
      allowEmpty - New allowEmpty value. Default value is false
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAllowEmpty

      public Boolean getAllowEmpty()
      If set to false, the last clause cannot be removed.
      Returns:
      Current allowEmpty value. Default value is false

    • setAllowRelatedRecordCriteria

      public FilterBuilder setAllowRelatedRecordCriteria(Boolean allowRelatedRecordCriteria) throws IllegalStateException
      Should related record criteria be allowed as either the field or value?

      This option is automatically enabled if allowAggregates is true unless explicitly set to false.

      This feature is available with Power or better licenses only. See smartclient.com/product for details.

      Parameters:
      allowRelatedRecordCriteria - New allowRelatedRecordCriteria value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAllowRelatedRecordCriteria

      public Boolean getAllowRelatedRecordCriteria()
      Should related record criteria be allowed as either the field or value?

      This option is automatically enabled if allowAggregates is true unless explicitly set to false.

      This feature is available with Power or better licenses only. See smartclient.com/product for details.

      Returns:
      Current allowRelatedRecordCriteria value. Default value is null

    • getBracket

      public Canvas getBracket()
      Note : This API is non-functional (always returns null) and exists only to make you aware that this MultiAutoChild exists. See Using AutoChildren for details.

      Widget used as a "bracket" to hint to the user that a subclause groups several field-by-field filter criteria under one logical operator.

      By default, a simple CSS-style Canvas with borders on three sides. A vertical StretchImg could provide a more elaborate appearance.

      Returns:
      null

    • getClauseStack

      public VStack getClauseStack() throws IllegalStateException
      VStack of all clauses that are part of this FilterBuilder

      This component is an AutoChild named "clauseStack". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current clauseStack value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setCriteria

      public FilterBuilder setCriteria(AdvancedCriteria criteria)
      Initial criteria.

      When initialized with criteria, appropriate clauses for editing the provided criteria will be automatically generated.

      Note that empty or partial criteria are allowed, for example, criteria that specify Criterion.fieldName only will generate an expression with the operator not chosen yet, and a Criterion with a logical operator ("and" or "or") but not subcriteria defined will generate an empty subclause.

      If this method is called after the component has been drawn/initialized: Set new criteria for editing.

      An interface for editing the provided criteria will be generated identically to what happens when initialized with Criteria.

      Any existing criteria entered by the user will be discarded.

      Parameters:
      criteria - new criteria. Pass null or {} to effectively reset the filterBuilder to it's initial state when no criteria are specified. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls

    • getCriteria

      public AdvancedCriteria getCriteria()
      Initial criteria.

      When initialized with criteria, appropriate clauses for editing the provided criteria will be automatically generated.

      Note that empty or partial criteria are allowed, for example, criteria that specify Criterion.fieldName only will generate an expression with the operator not chosen yet, and a Criterion with a logical operator ("and" or "or") but not subcriteria defined will generate an empty subclause.

      Returns:
      Get the criteria entered by the user. Default value is null

    • getDataSource

      public DataSource getDataSource()
      DataSource this filter should use for field definitions and available Operators.
      Returns:
      Current dataSource value. Default value is null

    • getDataSourceAsString

      public String getDataSourceAsString()
      DataSource this filter should use for field definitions and available Operators.
      Returns:
      Current dataSource value. Default value is null

    • setFieldDataSource

      public FilterBuilder setFieldDataSource(DataSource fieldDataSource) throws IllegalStateException
      If specified, the FilterBuilder will dynamically fetch DataSourceField definitions from this DataSource rather than using dataSource. The FieldPicker will default to being a ComboBoxItem rather than a SelectItem so that the user will have type-ahead auto-completion.

      The records returned from the fieldDataSource must have properties corresponding to a DataSourceField definition, at a minimum, "name" and "type". Any property legal on a DataSourceField is legal on the returned records, including valueMap.

      Even when a fieldDataSource is specified, dataSource may still be specified in order to control the list of valid operators for each field.

      Parameters:
      fieldDataSource - New fieldDataSource value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFieldDataSource

      public DataSource getFieldDataSource()
      If specified, the FilterBuilder will dynamically fetch DataSourceField definitions from this DataSource rather than using dataSource. The FieldPicker will default to being a ComboBoxItem rather than a SelectItem so that the user will have type-ahead auto-completion.

      The records returned from the fieldDataSource must have properties corresponding to a DataSourceField definition, at a minimum, "name" and "type". Any property legal on a DataSourceField is legal on the returned records, including valueMap.

      Even when a fieldDataSource is specified, dataSource may still be specified in order to control the list of valid operators for each field.

      Returns:
      Current fieldDataSource value. Default value is null

    • setFieldPickerProperties

      public FilterBuilder setFieldPickerProperties(FormItem fieldPickerProperties) throws IllegalStateException
      Properties to combine with the FieldPicker autoChild FormItem.
      Parameters:
      fieldPickerProperties - New fieldPickerProperties value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFieldPickerProperties

      public FormItem getFieldPickerProperties()
      Properties to combine with the FieldPicker autoChild FormItem.
      Returns:
      Current fieldPickerProperties value. Default value is null

    • setFieldPickerTitle

      public FilterBuilder setFieldPickerTitle(String fieldPickerTitle) throws IllegalStateException
      The title for the field-picker select-item.
      Parameters:
      fieldPickerTitle - New fieldPickerTitle value. Default value is "Field Name"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFieldPickerTitle

      public String getFieldPickerTitle()
      The title for the field-picker select-item.
      Returns:
      Current fieldPickerTitle value. Default value is "Field Name"

    • setFieldPickerWidth

      public FilterBuilder setFieldPickerWidth(Integer fieldPickerWidth) throws IllegalStateException
      Width for the field picker formItem displayed in clauses within this FilterBuilder.
      Parameters:
      fieldPickerWidth - New fieldPickerWidth value. Default value is "*"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFieldPickerWidth

      public Integer getFieldPickerWidth()
      Width for the field picker formItem displayed in clauses within this FilterBuilder.
      Returns:
      Current fieldPickerWidth value. Default value is "*"

    • setFieldPickerWidth

      public FilterBuilder setFieldPickerWidth(String fieldPickerWidth) throws IllegalStateException
      Width for the field picker formItem displayed in clauses within this FilterBuilder.
      Parameters:
      fieldPickerWidth - New fieldPickerWidth value. Default value is "*"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFieldPickerWidthAsString

      public String getFieldPickerWidthAsString()
      Width for the field picker formItem displayed in clauses within this FilterBuilder.
      Returns:
      Current fieldPickerWidth value. Default value is "*"

    • setFieldQueryWindowTitle

      public FilterBuilder setFieldQueryWindowTitle(String fieldQueryWindowTitle) throws IllegalStateException
      The title for the window that opens when a field query is selected.
      Parameters:
      fieldQueryWindowTitle - New fieldQueryWindowTitle value. Default value is "Define field query"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getFieldQueryWindowTitle

      public String getFieldQueryWindowTitle()
      The title for the window that opens when a field query is selected.
      Returns:
      Current fieldQueryWindowTitle value. Default value is "Define field query"
      See Also:

    • setIconBaseStyle

      public FilterBuilder setIconBaseStyle(String iconBaseStyle) throws IllegalStateException
      CSS class to apply to the add and remove clause buttons.
      Parameters:
      iconBaseStyle - New iconBaseStyle value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getIconBaseStyle

      public String getIconBaseStyle()
      CSS class to apply to the add and remove clause buttons.
      Returns:
      Current iconBaseStyle value. Default value is null
      See Also:

    • setIconSize

      public FilterBuilder setIconSize(Integer iconSize) throws IllegalStateException
      When set, dictates the size of the add and remove clause buttons.
      Parameters:
      iconSize - New iconSize value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getIconSize

      public Integer getIconSize()
      When set, dictates the size of the add and remove clause buttons.
      Returns:
      Current iconSize value. Default value is null

    • setInlineAndNotTitle

      public FilterBuilder setInlineAndNotTitle(String inlineAndNotTitle) throws IllegalStateException
      Title for the "And Not" operator (only applicable to the "inline" appearance)
      Parameters:
      inlineAndNotTitle - New inlineAndNotTitle value. Default value is "and not"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getInlineAndNotTitle

      public String getInlineAndNotTitle()
      Title for the "And Not" operator (only applicable to the "inline" appearance)
      Returns:
      Current inlineAndNotTitle value. Default value is "and not"

    • setInlineAndTitle

      public FilterBuilder setInlineAndTitle(String inlineAndTitle) throws IllegalStateException
      Title for the "And" operator (only applicable to the "inline" appearance)
      Parameters:
      inlineAndTitle - New inlineAndTitle value. Default value is "and"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getInlineAndTitle

      public String getInlineAndTitle()
      Title for the "And" operator (only applicable to the "inline" appearance)
      Returns:
      Current inlineAndTitle value. Default value is "and"

    • setInlineOrTitle

      public FilterBuilder setInlineOrTitle(String inlineOrTitle) throws IllegalStateException
      Title for the "Or" operator (only applicable to the "inline" appearance)
      Parameters:
      inlineOrTitle - New inlineOrTitle value. Default value is "or"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getInlineOrTitle

      public String getInlineOrTitle()
      Title for the "Or" operator (only applicable to the "inline" appearance)
      Returns:
      Current inlineOrTitle value. Default value is "or"

    • setLastClausePrompt

      public FilterBuilder setLastClausePrompt(String lastClausePrompt)
      The hover prompt text for the remove button in the last remaining clause, when allowEmpty is false.
      Parameters:
      lastClausePrompt - New lastClausePrompt value. Default value is "The last clause cannot be removed"
      Returns:
      FilterBuilder instance, for chaining setter calls

    • getLastClausePrompt

      public String getLastClausePrompt()
      The hover prompt text for the remove button in the last remaining clause, when allowEmpty is false.
      Returns:
      Current lastClausePrompt value. Default value is "The last clause cannot be removed"

    • setMatchAllTitle

      public FilterBuilder setMatchAllTitle(String matchAllTitle) throws IllegalStateException
      Title for the "Match All" (and) operator when using topOperatorAppearance:"radio".
      Parameters:
      matchAllTitle - New matchAllTitle value. Default value is "Match All"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMatchAllTitle

      public String getMatchAllTitle()
      Title for the "Match All" (and) operator when using topOperatorAppearance:"radio".
      Returns:
      Current matchAllTitle value. Default value is "Match All"

    • setMatchAnyTitle

      public FilterBuilder setMatchAnyTitle(String matchAnyTitle) throws IllegalStateException
      Title for the "Match Any" (or) operator when using topOperatorAppearance:"radio".
      Parameters:
      matchAnyTitle - New matchAnyTitle value. Default value is "Match Any"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMatchAnyTitle

      public String getMatchAnyTitle()
      Title for the "Match Any" (or) operator when using topOperatorAppearance:"radio".
      Returns:
      Current matchAnyTitle value. Default value is "Match Any"

    • setMatchNoneTitle

      public FilterBuilder setMatchNoneTitle(String matchNoneTitle) throws IllegalStateException
      Title for the "Match None" (not) operator when using topOperatorAppearance:"radio".
      Parameters:
      matchNoneTitle - New matchNoneTitle value. Default value is "Match None"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMatchNoneTitle

      public String getMatchNoneTitle()
      Title for the "Match None" (not) operator when using topOperatorAppearance:"radio".
      Returns:
      Current matchNoneTitle value. Default value is "Match None"

    • setMissingFieldPrompt

      public FilterBuilder setMissingFieldPrompt(String missingFieldPrompt) throws IllegalStateException
      The message to display next to fieldNames that do not exist in the available dataSource.
      Parameters:
      missingFieldPrompt - New missingFieldPrompt value. Default value is "[missing field definition]"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMissingFieldPrompt

      public String getMissingFieldPrompt()
      The message to display next to fieldNames that do not exist in the available dataSource.
      Returns:
      Current missingFieldPrompt value. Default value is "[missing field definition]"

    • getModeSwitcher

      public Label getModeSwitcher() throws IllegalStateException
      Label to change between simple and advanced mode. When clicked the filter mode is switched to the other mode. This label is only shown if showModeSwitcher is true.

      Shows either modeSwitcherSimpleMessage or modeSwitcherAdvancedMessage depending on the current state of the filter.

      This component is an AutoChild named "modeSwitcher". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current modeSwitcher value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setModeSwitcherAdvancedMessage

      public FilterBuilder setModeSwitcherAdvancedMessage(String modeSwitcherAdvancedMessage) throws IllegalStateException
      Title for the "Advanced.." mode switcher label (only applicable to the "radio" appearance).
      Parameters:
      modeSwitcherAdvancedMessage - New modeSwitcherAdvancedMessage value. Default value is "Advanced.."
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getModeSwitcherAdvancedMessage

      public String getModeSwitcherAdvancedMessage()
      Title for the "Advanced.." mode switcher label (only applicable to the "radio" appearance).
      Returns:
      Current modeSwitcherAdvancedMessage value. Default value is "Advanced.."

    • setModeSwitcherFlattenWarningMessage

      public FilterBuilder setModeSwitcherFlattenWarningMessage(String modeSwitcherFlattenWarningMessage) throws IllegalStateException
      Message displayed when switching to "radio" mode if the criteria will be logically changed.
      Parameters:
      modeSwitcherFlattenWarningMessage - New modeSwitcherFlattenWarningMessage value. Default value is "Criteria will be modified to fit in simpler editing interface"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getModeSwitcherFlattenWarningMessage

      public String getModeSwitcherFlattenWarningMessage()
      Message displayed when switching to "radio" mode if the criteria will be logically changed.
      Returns:
      Current modeSwitcherFlattenWarningMessage value. Default value is "Criteria will be modified to fit in simpler editing interface"

    • setModeSwitcherSimpleMessage

      public FilterBuilder setModeSwitcherSimpleMessage(String modeSwitcherSimpleMessage) throws IllegalStateException
      Title for the "Simple Mode.." mode switcher label (only applicable to the "bracket" appearance).
      Parameters:
      modeSwitcherSimpleMessage - New modeSwitcherSimpleMessage value. Default value is "Simple Mode.."
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getModeSwitcherSimpleMessage

      public String getModeSwitcherSimpleMessage()
      Title for the "Simple Mode.." mode switcher label (only applicable to the "bracket" appearance).
      Returns:
      Current modeSwitcherSimpleMessage value. Default value is "Simple Mode.."

    • getOperatorPicker

      public SelectItem getOperatorPicker()
      Note : This API is non-functional (always returns null) and exists only to make you aware that this MultiAutoChild exists. See Using AutoChildren for details.

      AutoChild for the FormItem that allows a user to select the operator when creating filter clauses. Each clause will create an operatorPicker automatically. To customize this item, use operatorPickerProperties

      Returns:
      null

    • setOperatorPickerProperties

      public FilterBuilder setOperatorPickerProperties(FormItem operatorPickerProperties) throws IllegalStateException
      Properties to combine with the operatorPicker autoChild FormItem.
      Parameters:
      operatorPickerProperties - New operatorPickerProperties value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOperatorPickerProperties

      public FormItem getOperatorPickerProperties()
      Properties to combine with the operatorPicker autoChild FormItem.
      Returns:
      Current operatorPickerProperties value. Default value is null

    • setOperatorPickerTitle

      public FilterBuilder setOperatorPickerTitle(String operatorPickerTitle) throws IllegalStateException
      The title for the operator-picker select-item.
      Parameters:
      operatorPickerTitle - New operatorPickerTitle value. Default value is "Operator"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOperatorPickerTitle

      public String getOperatorPickerTitle()
      The title for the operator-picker select-item.
      Returns:
      Current operatorPickerTitle value. Default value is "Operator"

    • setOperatorPickerWidth

      public FilterBuilder setOperatorPickerWidth(Integer operatorPickerWidth) throws IllegalStateException
      Width for the operator picker formItem displayed in clauses within this FilterBuilder.
      Parameters:
      operatorPickerWidth - New operatorPickerWidth value. Default value is 150
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOperatorPickerWidth

      public Integer getOperatorPickerWidth()
      Width for the operator picker formItem displayed in clauses within this FilterBuilder.
      Returns:
      Current operatorPickerWidth value. Default value is 150

    • setOperatorPickerWidth

      public FilterBuilder setOperatorPickerWidth(String operatorPickerWidth) throws IllegalStateException
      Width for the operator picker formItem displayed in clauses within this FilterBuilder.
      Parameters:
      operatorPickerWidth - New operatorPickerWidth value. Default value is 150
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOperatorPickerWidthAsString

      public String getOperatorPickerWidthAsString()
      Width for the operator picker formItem displayed in clauses within this FilterBuilder.
      Returns:
      Current operatorPickerWidth value. Default value is 150

    • getRadioOperatorForm

      public DynamicForm getRadioOperatorForm() throws IllegalStateException
      With TopOperatorAppearance:"radio", form that appears above the stack of clauses and allows picking the LogicalOperator for the overall FilterBuilder.

      By default, consists of a simple RadioGroupItem.

      This component is an AutoChild named "radioOperatorForm". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current radioOperatorForm value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • getRadioOperatorLayout

      public HLayout getRadioOperatorLayout() throws IllegalStateException
      HLayout of radioOperationForm and optional modeSwitcher.

      This component is an AutoChild named "radioOperatorLayout". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current radioOperatorLayout value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setRadioOperatorTitle

      public FilterBuilder setRadioOperatorTitle(String radioOperatorTitle) throws IllegalStateException
      The title for the Operator RadioGroupItem displayed in the radioOperatorForm.
      Parameters:
      radioOperatorTitle - New radioOperatorTitle value. Default value is "Overall Operator"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getRadioOperatorTitle

      public String getRadioOperatorTitle()
      The title for the Operator RadioGroupItem displayed in the radioOperatorForm.
      Returns:
      Current radioOperatorTitle value. Default value is "Overall Operator"

    • setRangeSeparator

      public FilterBuilder setRangeSeparator(String rangeSeparator) throws IllegalStateException
      For operators that check that a value is within a range, text to show between the start and end input fields for specifying the limits of the range.
      Parameters:
      rangeSeparator - New rangeSeparator value. Default value is "and"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getRangeSeparator

      public String getRangeSeparator()
      For operators that check that a value is within a range, text to show between the start and end input fields for specifying the limits of the range.
      Returns:
      Current rangeSeparator value. Default value is "and"

    • getRemoveButton

      public ImgButton getRemoveButton() throws IllegalStateException
      The removal ImgButton that appears before each clause if showRemoveButton is set.

      This component is an AutoChild named "removeButton". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current removeButton value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setRemoveButtonPrompt

      public FilterBuilder setRemoveButtonPrompt(String removeButtonPrompt) throws IllegalStateException
      The hover prompt text for the remove button.
      Parameters:
      removeButtonPrompt - New removeButtonPrompt value. Default value is "Remove"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getRemoveButtonPrompt

      public String getRemoveButtonPrompt()
      The hover prompt text for the remove button.
      Returns:
      Current removeButtonPrompt value. Default value is "Remove"

    • setRetainValuesAcrossFields

      public FilterBuilder setRetainValuesAcrossFields(Boolean retainValuesAcrossFields)
      Dictates whether values entered by a user should be retained in the value fields when a different field is selected. Default value is true.

      Note that, when switching between fields that have an optionDataSource or valueMap, this property is ignored and the values are never retained.

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

    • getRetainValuesAcrossFields

      public Boolean getRetainValuesAcrossFields()
      Dictates whether values entered by a user should be retained in the value fields when a different field is selected. Default value is true.

      Note that, when switching between fields that have an optionDataSource or valueMap, this property is ignored and the values are never retained.

      Returns:
      Current retainValuesAcrossFields value. Default value is true

    • setSaveOnEnter

      public FilterBuilder setSaveOnEnter(Boolean saveOnEnter) throws IllegalStateException
      If true, when the user hits the Enter key while focused in a text-item in this FilterBuilder, we automatically invoke the user-supplied FilterBuilder.search() method.
      Parameters:
      saveOnEnter - New saveOnEnter value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSaveOnEnter

      public Boolean getSaveOnEnter()
      If true, when the user hits the Enter key while focused in a text-item in this FilterBuilder, we automatically invoke the user-supplied FilterBuilder.search() method.
      Returns:
      Current saveOnEnter value. Default value is null

    • setShowAddButton

      public FilterBuilder setShowAddButton(Boolean showAddButton) throws IllegalStateException
      If set, a button will be shown underneath all current clauses allowing a new clause to be added.
      Parameters:
      showAddButton - New showAddButton value. Default value is true
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowAddButton

      public Boolean getShowAddButton()
      If set, a button will be shown underneath all current clauses allowing a new clause to be added.
      Returns:
      Current showAddButton value. Default value is true

    • setShowFieldTitles

      public FilterBuilder setShowFieldTitles(Boolean showFieldTitles) throws IllegalStateException
      If true (the default), show field titles in the drop-down box used to select a field for querying. If false, show actual field names instead.
      Parameters:
      showFieldTitles - New showFieldTitles value. Default value is true
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowFieldTitles

      public Boolean getShowFieldTitles()
      If true (the default), show field titles in the drop-down box used to select a field for querying. If false, show actual field names instead.
      Returns:
      Current showFieldTitles value. Default value is true

    • setShowHiddenFields

      public FilterBuilder setShowHiddenFields(Boolean showHiddenFields) throws IllegalStateException
      By default only non-hidden fields are shown for selection. To include hidden fields for selection set this property to true.
      Parameters:
      showHiddenFields - New showHiddenFields value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowHiddenFields

      public Boolean getShowHiddenFields()
      By default only non-hidden fields are shown for selection. To include hidden fields for selection set this property to true.
      Returns:
      Current showHiddenFields value. Default value is null

    • setShowLastRemoveButton

      public FilterBuilder setShowLastRemoveButton(Boolean showLastRemoveButton) throws IllegalStateException
      If set to false and showing clause remove buttons and the last clause cannot be removed the remove clause button will be hidden.
      Parameters:
      showLastRemoveButton - New showLastRemoveButton value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowLastRemoveButton

      public Boolean getShowLastRemoveButton()
      If set to false and showing clause remove buttons and the last clause cannot be removed the remove clause button will be hidden.
      Returns:
      Current showLastRemoveButton value. Default value is null

    • setShowModeSwitcher

      public FilterBuilder setShowModeSwitcher(Boolean showModeSwitcher) throws IllegalStateException
      When enabled allows FilterBuilder in topOperatorAppearance:"radio" or topOperatorAppearance:"bracket" mode to be switch to the other view by the user. "radio" mode is considered simple where "bracket" mode is advanced mode.

      Note that when switching from "bracket" to "radio" mode any entered criteria will be flattened by calling DataSource.flattenCriteria(). If the criteria cannot be flattened without losing symantics (see DataSource.canFlattenCriteria()) the user is prompted to confirm.

      If showModeSwitcher is set and topOperatorAppearance is unset:

      • when first drawn, the filterBuilder will choose which mode to use based on the provided criteria if any: advanced mode ("bracket") will be used if AdvancedCriteria are provided which cannot be flattened without loss of data (see DataSource.canFlattenCriteria()), otherwise simple mode ("radio") will be used.
      • for any calls to setCriteria() after draw, the FilterBuilder will switch to advanced mode if the criteria cannot be shown in simple mode without losing information, but will never automatically switch to simple mode, but an explicit call setTopOperatorAppearance("radio") can be used to do so.
      Parameters:
      showModeSwitcher - New showModeSwitcher value. Default value is null
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getShowModeSwitcher

      public Boolean getShowModeSwitcher()
      When enabled allows FilterBuilder in topOperatorAppearance:"radio" or topOperatorAppearance:"bracket" mode to be switch to the other view by the user. "radio" mode is considered simple where "bracket" mode is advanced mode.

      Note that when switching from "bracket" to "radio" mode any entered criteria will be flattened by calling DataSource.flattenCriteria(). If the criteria cannot be flattened without losing symantics (see DataSource.canFlattenCriteria()) the user is prompted to confirm.

      If showModeSwitcher is set and topOperatorAppearance is unset:

      • when first drawn, the filterBuilder will choose which mode to use based on the provided criteria if any: advanced mode ("bracket") will be used if AdvancedCriteria are provided which cannot be flattened without loss of data (see DataSource.canFlattenCriteria()), otherwise simple mode ("radio") will be used.
      • for any calls to setCriteria() after draw, the FilterBuilder will switch to advanced mode if the criteria cannot be shown in simple mode without losing information, but will never automatically switch to simple mode, but an explicit call setTopOperatorAppearance("radio") can be used to do so.
      Returns:
      Current showModeSwitcher value. Default value is null
      See Also:

    • setShowRemoveButton

      public FilterBuilder setShowRemoveButton(Boolean showRemoveButton) throws IllegalStateException
      If set, a button will be shown for each clause allowing it to be removed.
      Parameters:
      showRemoveButton - New showRemoveButton value. Default value is true
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowRemoveButton

      public Boolean getShowRemoveButton()
      If set, a button will be shown for each clause allowing it to be removed.
      Returns:
      Current showRemoveButton value. Default value is true

    • setShowSelectionCheckbox

      public FilterBuilder setShowSelectionCheckbox(Boolean showSelectionCheckbox) throws IllegalStateException
      If true, causes a CheckboxItem to appear to the left of each clause in "inline" appearance. This checkbox allows the user to select individual clauses so that, for example, clauses can be removed from the filterBuilder by application code. This property is ignored for appearances other than "inline".
      Parameters:
      showSelectionCheckbox - New showSelectionCheckbox value. Default value is false
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowSelectionCheckbox

      public Boolean getShowSelectionCheckbox()
      If true, causes a CheckboxItem to appear to the left of each clause in "inline" appearance. This checkbox allows the user to select individual clauses so that, for example, clauses can be removed from the filterBuilder by application code. This property is ignored for appearances other than "inline".
      Returns:
      Current showSelectionCheckbox value. Default value is false

    • setShowSubClauseButton

      public FilterBuilder setShowSubClauseButton(Boolean showSubClauseButton) throws IllegalStateException
      Whether to show a button that allows the user to add subclauses. Defaults to false if the TopOperatorAppearance is "radio" or "inline", true in all other cases.
      Parameters:
      showSubClauseButton - New showSubClauseButton value. Default value is See Description
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowSubClauseButton

      public Boolean getShowSubClauseButton()
      Whether to show a button that allows the user to add subclauses. Defaults to false if the TopOperatorAppearance is "radio" or "inline", true in all other cases.
      Returns:
      Current showSubClauseButton value. Default value is See Description

    • setSortFields

      public FilterBuilder setSortFields(Boolean sortFields) throws IllegalStateException
      Should the FieldPicker items be sorted alphabetically in the drop down list.
      Parameters:
      sortFields - New sortFields value. Default value is true
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSortFields

      public Boolean getSortFields()
      Should the FieldPicker items be sorted alphabetically in the drop down list.
      Returns:
      Current sortFields value. Default value is true

    • setSpecialValuesCSS

      public FilterBuilder setSpecialValuesCSS(String specialValuesCSS) throws IllegalStateException
      CSS text to be added to the styling for Related Field and Aggregate selections in the field name picker. By default, the choices are italicized.
      Parameters:
      specialValuesCSS - New specialValuesCSS value. Default value is "font-style: italic"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSpecialValuesCSS

      public String getSpecialValuesCSS()
      CSS text to be added to the styling for Related Field and Aggregate selections in the field name picker. By default, the choices are italicized.
      Returns:
      Current specialValuesCSS value. Default value is "font-style: italic"

    • getSubClauseButton

      public IButton getSubClauseButton() throws IllegalStateException
      Button allowing the user to add subclauses grouped by a LogicalOperator.

      This component is an AutoChild named "subClauseButton". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current subClauseButton value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setSubClauseButtonPrompt

      public FilterBuilder setSubClauseButtonPrompt(String subClauseButtonPrompt) throws IllegalStateException
      The hover prompt text for the subClauseButton.
      Parameters:
      subClauseButtonPrompt - New subClauseButtonPrompt value. Default value is "Add Subclause"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSubClauseButtonPrompt

      public String getSubClauseButtonPrompt()
      The hover prompt text for the subClauseButton.
      Returns:
      Current subClauseButtonPrompt value. Default value is "Add Subclause"

    • setSubClauseButtonTitle

      public FilterBuilder setSubClauseButtonTitle(String subClauseButtonTitle) throws IllegalStateException
      The title of the subClauseButton
      Parameters:
      subClauseButtonTitle - New subClauseButtonTitle value. Default value is "+()"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getSubClauseButtonTitle

      public String getSubClauseButtonTitle()
      The title of the subClauseButton
      Returns:
      Current subClauseButtonTitle value. Default value is "+()"

    • setTopOperator

      public FilterBuilder setTopOperator(LogicalOperator topOperator)
      Default logical operator for all top-level clauses in the FilterBuilder.

      May be able to be changed by the user via the UI, according to TopOperatorAppearance.

      If this method is called after the component has been drawn/initialized: Programmatically change the topOperator for this FilterBuilder.

      Parameters:
      topOperator - new top-level operator. Default value is "and"
      Returns:
      FilterBuilder instance, for chaining setter calls

    • getTopOperator

      public LogicalOperator getTopOperator()
      Default logical operator for all top-level clauses in the FilterBuilder.

      May be able to be changed by the user via the UI, according to TopOperatorAppearance.

      Returns:
      Current topOperator value. Default value is "and"

    • setTopOperatorAppearance

      public FilterBuilder setTopOperatorAppearance(TopOperatorAppearance topOperatorAppearance)
      How to display and edit the top-level operator for this FilterBuilder.

      See TopOperatorAppearance for a list of options.

      If this method is called after the component has been drawn/initialized: Modify TopOperatorAppearance at runtime.

      Note that when changing from "bracket" to "radio" mode the criteria will be flattened by calling DataSource.flattenCriteria() which could result in a logical change to the criteria.

      Parameters:
      topOperatorAppearance - new topOperatorAppearance. Default value is "bracket"
      Returns:
      FilterBuilder instance, for chaining setter calls

    • getTopOperatorAppearance

      public TopOperatorAppearance getTopOperatorAppearance()
      How to display and edit the top-level operator for this FilterBuilder.

      See TopOperatorAppearance for a list of options.

      Returns:
      Current topOperatorAppearance value. Default value is "bracket"

    • getTopOperatorForm

      public DynamicForm getTopOperatorForm() throws IllegalStateException
      With TopOperatorAppearance "bracket" and "inline", a form that appears to the left of the stack of clauses and allows picking the LogicalOperator for the overall FilterBuilder (or for that specific FilterClause, in the case of "inline")

      By default, consists of a CheckboxItem if showSelectionCheckbox is true, and a simple SelectItem containing the available logical operators.

      If this FilterBuilder shows nested sub-clauses, the same defaults will be applied to the top-operator item for each sub-clause.

      This component is an AutoChild named "topOperatorForm". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current topOperatorForm value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • getTopOperatorItem

      public SelectItem getTopOperatorItem() throws IllegalStateException
      Automatically generated SelectItem autoChild shown in the topOperatorForm. Developers may customize this item using the standard autoChild pattern (by modifying topOperatorItemDefaults and topOperatorItemProperties).

      If this FilterBuilder shows nested sub-clauses, the same defaults will be applied to the top-operator item for each sub-clause.

      This component is an AutoChild named "topOperatorItem". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current topOperatorItem value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • setTopOperatorItemWidth

      public FilterBuilder setTopOperatorItemWidth(int topOperatorItemWidth) throws IllegalStateException
      Width for the topOperatorItem autoChild.
      Parameters:
      topOperatorItemWidth - New topOperatorItemWidth value. Default value is "*"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTopOperatorItemWidth

      public int getTopOperatorItemWidth()
      Width for the topOperatorItem autoChild.
      Returns:
      Current topOperatorItemWidth value. Default value is "*"

    • setTopOperatorItemWidth

      public FilterBuilder setTopOperatorItemWidth(String topOperatorItemWidth) throws IllegalStateException
      Width for the topOperatorItem autoChild.
      Parameters:
      topOperatorItemWidth - New topOperatorItemWidth value. Default value is "*"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTopOperatorItemWidthAsString

      public String getTopOperatorItemWidthAsString()
      Width for the topOperatorItem autoChild.
      Returns:
      Current topOperatorItemWidth value. Default value is "*"

    • setTopOperatorOptions

      public FilterBuilder setTopOperatorOptions(OperatorId... topOperatorOptions) throws IllegalStateException
      Logical operators to allow for TopOperatorAppearances of "radio" and "bracket".

      Note that this list may be further limited according to the available operators returned by the DataSource.

      Parameters:
      topOperatorOptions - New topOperatorOptions value. Default value is ["and", "or", "not"]
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTopOperatorOptions

      public OperatorId[] getTopOperatorOptions()
      Logical operators to allow for TopOperatorAppearances of "radio" and "bracket".

      Note that this list may be further limited according to the available operators returned by the DataSource.

      Returns:
      Current topOperatorOptions value. Default value is ["and", "or", "not"]

    • setTopOperatorTitle

      public FilterBuilder setTopOperatorTitle(String topOperatorTitle) throws IllegalStateException
      The title for the left-aligned Operator selectItem in the topOperatorForm.
      Parameters:
      topOperatorTitle - New topOperatorTitle value. Default value is "Clause Operator"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getTopOperatorTitle

      public String getTopOperatorTitle()
      The title for the left-aligned Operator selectItem in the topOperatorForm.
      Returns:
      Current topOperatorTitle value. Default value is "Clause Operator"

    • setValidateOnChange

      public FilterBuilder setValidateOnChange(Boolean validateOnChange) throws IllegalStateException
      If true (the default), validates each entered value when it changes, to make sure it is a a valid value of its type (valid string, number, and so on). No other validation is carried out. If you switch this property off, it is still possible to validate the FilterBuilder by calling validate() from your own code.
      Parameters:
      validateOnChange - New validateOnChange value. Default value is true
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValidateOnChange

      public Boolean getValidateOnChange()
      If true (the default), validates each entered value when it changes, to make sure it is a a valid value of its type (valid string, number, and so on). No other validation is carried out. If you switch this property off, it is still possible to validate the FilterBuilder by calling validate() from your own code.
      Returns:
      Current validateOnChange value. Default value is true

    • setValueItemWidth

      public FilterBuilder setValueItemWidth(Integer valueItemWidth) throws IllegalStateException
      Width for the value-chooser formItem displayed in clauses within this FilterBuilder. Note that depending on the selected operator type, this item may not be displayed, or may have different characteristics. See getValueFieldProperties() for information on customizing the value item.
      Parameters:
      valueItemWidth - New valueItemWidth value. Default value is 150
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueItemWidth

      public Integer getValueItemWidth()
      Width for the value-chooser formItem displayed in clauses within this FilterBuilder. Note that depending on the selected operator type, this item may not be displayed, or may have different characteristics. See getValueFieldProperties() for information on customizing the value item.
      Returns:
      Current valueItemWidth value. Default value is 150

    • setValueItemWidth

      public FilterBuilder setValueItemWidth(String valueItemWidth) throws IllegalStateException
      Width for the value-chooser formItem displayed in clauses within this FilterBuilder. Note that depending on the selected operator type, this item may not be displayed, or may have different characteristics. See getValueFieldProperties() for information on customizing the value item.
      Parameters:
      valueItemWidth - New valueItemWidth value. Default value is 150
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueItemWidthAsString

      public String getValueItemWidthAsString()
      Width for the value-chooser formItem displayed in clauses within this FilterBuilder. Note that depending on the selected operator type, this item may not be displayed, or may have different characteristics. See getValueFieldProperties() for information on customizing the value item.
      Returns:
      Current valueItemWidth value. Default value is 150

    • setValueQueryAggregateButtonPrompt

      public FilterBuilder setValueQueryAggregateButtonPrompt(String valueQueryAggregateButtonPrompt) throws IllegalStateException
      The hover prompt text for the dynamic value button.
      Parameters:
      valueQueryAggregateButtonPrompt - New valueQueryAggregateButtonPrompt value. Default value is "Define aggregate value query"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueQueryAggregateButtonPrompt

      public String getValueQueryAggregateButtonPrompt()
      The hover prompt text for the dynamic value button.
      Returns:
      Current valueQueryAggregateButtonPrompt value. Default value is "Define aggregate value query"

    • setValueQueryAggregatePrefix

      public FilterBuilder setValueQueryAggregatePrefix(String valueQueryAggregatePrefix) throws IllegalStateException
      The prefix to be displayed before a aggregate valueQuery value in the clause.
      Parameters:
      valueQueryAggregatePrefix - New valueQueryAggregatePrefix value. Default value is "Aggregation:"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueQueryAggregatePrefix

      public String getValueQueryAggregatePrefix()
      The prefix to be displayed before a aggregate valueQuery value in the clause.
      Returns:
      Current valueQueryAggregatePrefix value. Default value is "Aggregation:"

    • setValueQueryRelatedFieldButtonPrompt

      public FilterBuilder setValueQueryRelatedFieldButtonPrompt(String valueQueryRelatedFieldButtonPrompt) throws IllegalStateException
      The hover prompt text for the dynamic value button.
      Parameters:
      valueQueryRelatedFieldButtonPrompt - New valueQueryRelatedFieldButtonPrompt value. Default value is "Define related field value query"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueQueryRelatedFieldButtonPrompt

      public String getValueQueryRelatedFieldButtonPrompt()
      The hover prompt text for the dynamic value button.
      Returns:
      Current valueQueryRelatedFieldButtonPrompt value. Default value is "Define related field value query"

    • setValueQueryRelatedFieldPrefix

      public FilterBuilder setValueQueryRelatedFieldPrefix(String valueQueryRelatedFieldPrefix) throws IllegalStateException
      The prefix to be displayed before a related field valueQuery value in the clause.
      Parameters:
      valueQueryRelatedFieldPrefix - New valueQueryRelatedFieldPrefix value. Default value is "Related field:"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getValueQueryRelatedFieldPrefix

      public String getValueQueryRelatedFieldPrefix()
      The prefix to be displayed before a related field valueQuery value in the clause.
      Returns:
      Current valueQueryRelatedFieldPrefix value. Default value is "Related field:"

    • setValueQueryWindowTitle

      public FilterBuilder setValueQueryWindowTitle(String valueQueryWindowTitle) throws IllegalStateException
      The title for the window that opens when a value query is selected.

      This is a dynamic string - text within ${...} are dynamic variables and will be evaluated as JS code when the message is displayed.

      Only one dynamic variable, fieldTitle, is available.

      Parameters:
      valueQueryWindowTitle - New valueQueryWindowTitle value. Default value is "Define value query for field ${fieldTitle}"
      Returns:
      FilterBuilder instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getValueQueryWindowTitle

      public String getValueQueryWindowTitle()
      The title for the window that opens when a value query is selected.

      This is a dynamic string - text within ${...} are dynamic variables and will be evaluated as JS code when the message is displayed.

      Only one dynamic variable, fieldTitle, is available.

      Returns:
      Current valueQueryWindowTitle value. Default value is "Define value query for field ${fieldTitle}"
      See Also:

    • addClause

      public void addClause(FilterClause filterClause)
      Add a new FilterClause to this FilterBuilder.

      This API is intended for the rare use case of adding a highly customized FilterClause component that does not include the standard field/operator/value picking interface, instead providing a custom interface and returning a criterion via FilterClause.getCriterion().

      If you just want to programmatically add a new FilterClause showing a specific Criterion use addCriterion().

      If you want to use the standard field/operator/value interface but provide a custom control for editing the value, see DataSource.addSearchOperator() and Operator.editorType.

      Parameters:
      filterClause - A FilterClause instance

    • addCriterion

      public void addCriterion(Criterion criterion)
      Add a new criterion, including recursively adding sub-criteria for a criterion that contains other criteria.
      Parameters:
      criterion - new criterion to be added

    • clearCriteria

      public void clearCriteria()
      Clear all current criteria.

    • addFilterChangedHandler

      public HandlerRegistration addFilterChangedHandler(FilterChangedHandler handler)
      Add a filterChanged handler.

      Handler fired when there is a change() event fired on any FormItem within the filterBuilder.

      Specified by:
      addFilterChangedHandler in interface HasFilterChangedHandlers
      Parameters:
      handler - the filterChanged handler
      Returns:
      HandlerRegistration used to remove this handler

    • getEditorType

      public String getEditorType(DataSourceField field, OperatorId operatorId)
      Returns the type of editor to use for the field.

      Default behavior is to use the Operator.editorType for a custom operator, otherwise, use RelativeDateItem for before/after/between operators on date fields, otherwise, use the same editor as would be chosen by a SearchForm.

      Parameters:
      field - DataSourceField definition
      operatorId - OperatorId for the chosen operator
      Returns:
      Smart GWT class to use (must be subclass of FormItem). See SCClassName

    • getSelectedClauses

      public FilterClause[] getSelectedClauses()
      Returns the list of this FilterBuilder's FilterClauses that are currently selected. A clause is "selected" if the user has checked the checkbox next to it; therefore, this method always returns an empty list unless the showSelectionCheckbox property is set. This method is only applicable where TopOperatorAppearance is "inline" (because that is the only appearance that supports showSelectionCheckbox)
      Returns:
      The list of selected clauses

    • addSearchHandler

      public HandlerRegistration addSearchHandler(SearchHandler handler)
      Add a search handler.

      A StringMethod that is automatically invoked if FilterBuilder.saveOnEnter is set and the user presses Enter whilst in a text-item in any clause or subclause.

      Specified by:
      addSearchHandler in interface HasSearchHandlers
      Parameters:
      handler - the search handler
      Returns:
      HandlerRegistration used to remove this handler

    • validate

      public Boolean validate()
      Validate the clauses of this FilterBuilder.
      Returns:
      true if all clauses are valid, false otherwise

    • setDefaultProperties

      public static void setDefaultProperties(FilterBuilder filterBuilderProperties)
      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 set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. 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:
      filterBuilderProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • onInit

      public void onInit()
      Overrides:
      onInit in class Layout

    • onInit_FilterBuilder

      protected void onInit_FilterBuilder()

    • setShowFieldTitles

      public void setShowFieldTitles(boolean showFieldTitles) throws IllegalStateException
      If true (the default), show field titles in the drop-down box used to select a field for querying. If false, show actual field names instead.
      Parameters:
      showFieldTitles - showFieldTitles default is true
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • setDataSource

      public void setDataSource(DataSource dataSource)
      DataSource this filter should use for field definitions and available Operators.
      Parameters:
      dataSource - dataSource Default value is null

    • getCriteria

      public AdvancedCriteria getCriteria(boolean includeEmptyValues)
      Initial criteria.

      When initialized with criteria, appropriate clauses for editing the provided criteria will be automatically generated.

      Note that empty or partial criteria are allowed, for example, criteria that specify Criterion.fieldName only will generate an expression with the operator not chosen yet, and a Criterion with a logical operator ("and" or "or") but not subcriteria defined will generate an empty subclause.

      Parameters:
      By - default if a user has selected a field and operator type, but has failed to enter a value for the field it will be skipped. This optional parameter allows you to retrieve all criteria, including those with an empty value attribute.
      Returns:
      Get the criteria entered by the user. Default value is null

    • removeClause

      public void removeClause(FilterClause clause)
      Remove a clause this FilterBuilder is currently showing.
      Parameters:
      clause - clause as retrieved from filterBuilder.clauses

    • getMembers

      public Canvas[] getMembers()
      Description copied from class: Layout
      An array of canvases that will be contained within this layout. You can set the following properties on these canvases (in addition to the standard component properties):
      • layoutAlign -- specifies the member's alignment along the breadth axis; valid values are "top", "center" and "bottom" for a horizontal layout and "left", "center" and "right" for a vertical layout (see defaultLayoutAlign for default implementation.)
      • showResizeBar -- set to true to show a resize bar (default is false)
      Height and width settings found on members are interpreted by the Layout according to the layout policy.

      Note that it is valid to have null slots in the provided members Array, and the Layout will ignore those slots. This can be useful to keep code compact, for example, when constructing the members Array, you might use an expression that either returns a component or null depending on whether the component should be present. If the expression returns null, the null slot will be ignored by the Layout.

      Overrides:
      getMembers in class Layout
      Returns:
      Get the Array of members. Default value is null

    • getValueFieldProperties

      public FormItem getValueFieldProperties(FieldType type, String fieldName, OperatorId operatorId, ValueItemType itemType, String fieldType)
      Override to return properties for the FormItem(s) used for the "value" field displayed within clauses within this filterBuilder.

      Note that the valueType impacts when this method is called. For operators with valueType "fieldType" or "custom", a single value field is displayed. For operators with valueType "valueRange" two value-field items are displayed (one for the start and one for the end position). The valueItemType parameter may be used to determine which form item is being generated.

      Note : This is an override point

      Parameters:
      type - type of the DataSource field for this filter row. Note that for DataSourceSimpleTypeField SimpleType based DataSource fields this attribute will be null
      fieldName - name of the DataSource field for this filter row
      operatorId - OperatorId for the chosen operator
      itemType - What valueItem is being generated.
      fieldType - type of the DataSource field for this filter row. Typically one would use the parameter but this value is useful when the FieldType is a custom SimpleType in which case the type will be FieldType.CUSTOM and this parameter is the name of the SimpleType
      Returns:
      properties for the value field

    • setFieldOperatorCustomizer

      public void setFieldOperatorCustomizer(FieldOperatorCustomizer customizer)
      This method installs a customizer that returns the set of OperatorIds applicable to the passed fieldName
      Parameters:
      customizer - the customizer to execute.

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(FilterBuilderLogicalStructure s)
      Setter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.

    • getLogicalStructure

      public LogicalStructureObject getLogicalStructure()
      Getter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.
      Specified by:
      getLogicalStructure in interface LogicalStructure
      Overrides:
      getLogicalStructure in class Layout