Filter Set

The Filter Set component is a container for one or more filters that can be used to filter the data within multiple components, provided they are attached to the same model.

Note

Individual filters can also be created as elements within Skuid’s other components. If your page is focused on one model—especially within one table—table filters may be sufficient. However, due to its exclusive features, using the Filter Set component is best practice for many design scenarios.

Using the Filter Set Component

The Filter Set component can hold one or more filters. Filters operate by creating a condition—or interacting with an existing one—within the Filter Set component’s specified model. When a user uses the filter, it activates and sets that condition’s value—filtering and limiting the data pulled into the component by that particular model.

To use the Filter Set:

  • Add a Filter Set to a page, and adjust the Filters properties within the properties pane to govern the layout of the filters within the component.
  • Add one (or more) individual filters to the component, then configure those filters using the Filter Properties. (For each filter, you can choose from several filter types.)

Note

Each Filter Set component can be attached to one model, and its filters will affect all other components attached to that model.

To use one filter for multiple components, simply set those components to use the same model.

Best Practices

  • Filter buttons arranged vertically will display across the full width of the Filter Set container—which stretches across the page by default. Try using this component within a Responsive Grid to better control the page layout.
  • Filters and search options are automatically disabled when a change is made to a record (but not yet saved to the model). After the change is saved, these options are once again accessible.
  • Make it clear via positioning and labeling which components will be affected by a Filter Set.
  • Use the Filter Set to filter visualizations.
  • If the only component requiring a filter is a table, it might be more efficient to use a Table Filter.
  • By default, Skuid remembers filters and other Personalization Settings server side (on the user record) rather than client-side (using browser cookies).

Properties

Filter Set Properties

The properties for the Filter Set component.

Basic tab [[]]

  • Model: Select the model that the filters within the Filter Set will affect.
  • Layout: This field will determine how filters are placed within the Filter Set container.
    • Horizontal: Filters will appear as tiny buttons arranged horizontally.
    • Vertical: Filters will be arranged vertically, and each filter will stretch to fill the horizontal area of the Filter Set.
  • Position: Used for horizontal layouts, this determines whether filters are placed on the left or right side of the Filter Set container.

Filters & Search tab [[]]

In this tab are properties that control whether or not you have a search box, and when search terms and conditions are applied.

  • Filter & Search Behavior:

    • Apply Filters and Search Immediately: If checked, all changes made to filters, or any text typed into the search bar, will be applied immediately. If unchecked, Skuid displays the Apply and Cancel buttons. The changes will not be applied until the end user selects Apply.

      Note

      This is particularly useful when employing multiple filter criteria.

  • Search Properties:

    • Show Search Box: If checked, Skuid displays a search box above the component.

    • Search Method: Determines if a search will query the server and filter its data, or filter local data on the client.

      • Server (default): Returns search results from all data on the server.

      • Client: Returns search results from only the data that is currently loaded on the page. Large data sets may require lengthy time to filter. If end users commonly need to sort only the data they have loaded within the page—as opposed to every record on the server—this property may speed the filter process.

        Warning

        If the server contains a large data set not yet loaded into the page, but Search Method is set to Client, the filter may return incomplete results because it’s filtering incomplete data. This may result in unexpected omissions.

    • Tokenize Search Terms: If checked, each word typed into the search bar is “tokenized” — meaning each word is searched for individually. A tokenized search for “George Washington” returns any record with “George” and “Washington”. For example, “George Washington,” “George Michael Washington,” and “George is headed to Washington”. An untokenized search for “George Washington” returns only records with “George Washington” exactly.

    • Search box placeholder text: The text that appears in the search box before the end user starts a search. (The default is “Search.”)

    • Empty Search Behavior lets you determine what happens when the search box is emptied.

      • Re-query for Model Data (default): The data displayed in the component returns to the state it was in when you first loaded the page.

      • Remove all Model Data: The data is removed from the component and its associated model (but not from the data object).

        Note

        Why do this? If you want to use a component to display the list of search results—handy when you have a lot of search results—you need to have an empty component each time you do a new search, so you can display the newly returned results in it. Without this property, the component’s model will be re-queried when the text is cleared from the search box.

  • Search Fields: Specifies which fields will be searched against from the component’s search bar.

    Note

    Depending on the data source used for the model attached to the component, this property may not be available.

    • Use SOSL to improve search performance (Salesforce data sources only): SOSL quickly can search multiple objects at a time within a single search query. SOSL does not directly search the database, but instead queries an index of Salesforce text fields. Individual search fields may not be added when this property is enabled.

      Warning

      Because the search is against the index, results are limited to what is present in the index, and will not include data that may have been recently updated in the database. The index updates very quickly, but expect a delay of up to 30 seconds between changes made to the database, and their appearance in the search results.

      Note

      SOSL can search Text fields (including Long Text fields), but not Picklist fields and Reference fields.

      • Fields to Search: Sets which Types of fields to query with SOSL. The options are:

        • Name Fields (default)
        • All Text Fields
        • Email Field
        • Phone Fields
        • SideBar Fields (Name, Phone, Email, External Ids)

        Searches on Salesforce data sources can use one of two query languages: SOQL or SOSL. SOQL can only search one object at a time in a single query, but searches all searchable fields in that object in real-time.

    • Fields: Skuid searches on searchable fields by default. Search can be narrowed to individual fields by clicking fa-plus-circle Add new Search Field, and then using the field picker to select the field.

      Note

      • (Salesforce data sources only) SOQL can search Picklist fields and Reference fields, but not Long Text fields.
      • You can add multiple search fields.
      • Search Operator: Select from the following logical operators:

        • =
        • starts with
        • Contains
Skuid SFX [[]]

By default, Salesforce Objects use SOQL. To ensure proper functionality, enable the Allow Search property on any Salesforce objects to be included in the search.

For more information on using these search options with Salesforce, check out Salesforce’s SOQL and SOSL Reference Guide.

Advanced tab [[]]

Display Logic tab[[]]

Standard display logic options are available.

Filter Properties

Properties for the individual filters. Skuid includes the following automatic filters:

  • Date Range: Filters a table to display items that fall within a selected date range.
  • Numeric Range: Filters a table to display items that fall within the designated numeric range.
  • Multi-Select Option: Select more than one filter criteria; when activated, displays items that meet those criteria.
  • Select Option: Filters a table to display items that meet a specified filter criteria.
  • Toggle: Toggle a filter on or off; when activated, displays only items that meet the filter criteria; click the toggle filter again to display all items.

Each filter type includes the Filter Method property, which offers two options:

  • Client: Returns filter results from only the data that is currently loaded on the page. Large data sets may require lengthy time to filter. If users commonly need to sort only the data they have loaded within the page—as opposed to every record on the server—this property may speed the filter process.

Warning

If the server contains a large data set not yet loaded into the page, but Filter Method is set to Client, the filter results will be only a subset of the complete data set. This may result in unexpected omissions.

  • Server: (Default) Returns filter results from all data on the server.

Additional properties for the individual filters (by Filter Type):

Date Range [[]]

Condition Source: Auto Generate Condition

Skuid uses the chosen Date/Datetime field to filter.

  • Date/Datetime Field: Select the field (that returns a date) to filter on from the picklist. The Filter button will drop down a set of entry fields for start date and end date.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.
Condition Source: Specify Existing Conditions

Skuid requires a condition to use as the filter.

  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Begin Model Condition and End Model Condition: Appears when Specify Existing Conditions is selected. For Data Range and Numeric Range, use model conditions to limit the Start value and End value for the ranges.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.

Numeric Range [[]]

Condition Source: Auto Generate Condition

Skuid uses the chosen Numeric field as the filter.

  • Numeric Field: Select the field (that returns a number) to filter on from the picklist. The Filter button will drop down a set of entry fields for minimum and maximum amount.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.
Condition Source: Specify Existing Conditions

Skuid requires a condition to use as the filter.

  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Begin Model Condition and End Model Condition: Appears when Specify Existing Conditions is selected. For Data Range and Numeric Range, use model conditions to limit the Start value and End value for the ranges.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.

Multi-select Option [[]]

Pick Options and Conditions: Automatically

Note

Automatically generating the list of filter options is the best choice in most situations.

  • Filter Field: Select the field to filter on from the picklist. This will populate the Filter dropdown list with filter options.
  • Filter Condition Operator:
    • in: Display only the data that is within the filter condition.
    • not in: Display only the data that is not within the filter condition.
  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.
Pick Options and Conditions: Manually

Note

Manually generating the list of filter options can be more complicated. However for builders working with multiple or complex model conditions, or those desiring a higher degree of granularity, manually creating the option list can be a useful alternative.

  • Model Condition to Affect: Select the model condition used to limit the number of displayed values for a filtered field.
  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.

Select Option (default) [[]]

Pick Options and Conditions: Automatically

Note

Automatically generating the list of filter options is the best choice in most situations.

Displays all possible options for a filter:

  • Filter Field: Select the field to filter on from the picklist. This will populate the Filter dropdown list with filter options.
  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Maximum Height (optional): Choose the size of the Filter button’s dropdown option menu.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.
Pick Options and Conditions: Manually

Note

Manually generating the list of filter options can be more complicated. However for builders working with multiple or complex model conditions, or those desiring a higher degree of granularity, manually creating the option list can be a useful alternative.

Uses a condition to limit the number of choosable options for the filter:

  • Model Condition to Affect: Select the model condition used to limit the number of displayed values for a filtered field.
  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.
  • Switch Filter to Autocomplete at X items: If a Filter has more than 25 options, the filter shifts from a button with a dropdown, to an autocomplete field. Change this number to trigger that transition at a higher, or lower, number of options.
  • Show Label above Filter:
    • Yes, use Field’s label
    • Yes, use Custom label
    • No
  • Filter label: Enter the label for the filter button.
  • “None Selected” Option text: Enter the text displayed on the Filter button if no filter selections have been made.
Sources [[]]

Choosing Pick Options and Condition(s) Manally with Select Option as the Filter Type activates the Sources feature, which allows you to control where the list of options that are listed on the filter are sourced from.

Click fa-plus-circle Add Option Source, and then configure the Source Type:

  • Manual: Manually create the list of filter options. Choosing this property activates the Option feature.

    Click fa-plus-circle Option on the filter source, then configure. Drag and drop manual filter source entries to reorder them. Each option added has the following properties:

    • What Condition(s) will this Option affect?:

      • Affect the Default Condition: The option selected is used as the value in the model’s default condition.

        • Value: The data to be passed from this option item to the model condition. For example, if the value is set as 42 and the end user selects this option from the list, then the value of 42 is passed into the model condition.
      • Affect Other Condition(s): The option selected is used as the value in other conditions on the model, but not on the default condition.

        • Choosing this property activates the Effect feature.

          Click fa-plus-circle Effect on the filter option, then configure:

          • Action: Activate or deactivate a model condition. This action works in relation to the condition’s state (Always On, Filterable Default On, Filterable Default Off, Always Off).

            • Activate and Set Value: Activate and set the condition to a specific value.
            • Activate: Activate the condition without setting a value. Typically used for conditions with Always Off or Filterable Default Off states.
            • De-Activate: Deactivate the condition.
          • Model Condition: The model condition to interact with.

          • Value: The value to set the condition to when using the Activate and Set Value option.

      • Label: A user-friendly label for option.
  • Rows in a Model: Use the values in the rows of a model as the source for the filter’s options. Use this feature to create a dynamic picklist that can update with user input.

    Why use this? When accessing the values from a selected model using Pick Options and Conditions > Automatically, Skuid only lists values that have records associated with them; “empty” values (values with no associated records) do not display on the dropdown. To ensure that all values—even newly-added—are included in the list of filter options, use Pick Options and Conditions > Manually and select this property for the Source Type.

    Note

    Filter values display according to the default order provided in the model. To change that order: in the model used to provide the filter source, include the API name (StageName, not Stage) for the field in the Fields to order records by property followed by either ASC (Z to A) or DESC (A to Z); for example StageName DESC.

    • Merge Source: The model which contains the field employed in the default condition for this filter.

    • Option Label Template: The label for the filter option. This property accepts typed text or merge syntax (in triple brackets).

    • Which Conditions will this Source’s Options affect?:

      • Just the Default Condition
      • Default Condition and others
    • Value to Inject into the Default Condition: This defaults to {{Id}}, but can be changed to any field in the model associated with the condition.

Warning

Be sure to include the double curly brackets to designate the value as a merge variable; if missing, the condition may misread the merge syntax and throw an error.

  • Picklist Options for Condition’s Field: Use a picklist field as the source for the filter’s options. If there is a specific requirement to Pick Options and Conditions for the filter manually, this property replicates the results of using Pick Options and Conditions > Automatically: employing the field designated in the condition as the source of the filter options.

    • Label Prefix (optional): Text inserted before the filter’s label. For example, if the filter is on the Status field (with categories such as New, Closed, Pending, etc.), adding a prefix of Status: results in Option labels such as Status: New; Status: Closed; Status: Pending.
    • Label Suffix (optional): Similar to Label Suffix, text to be inserted after the filter’s label. If the filter is on the Status field (with categories such as New, Closed, Pending, etc.), adding a suffix of Status results in Option labels such as New Status; Closed Statis; Pending Status.
  • Custom Source (Snippet): Use a JavaScript snippet as the source for the filter’s options. The filter options are created from objects within the snippet. To learn more, see Use a JavaScript Snippet as a Filter Option Source.

    • Snippet Name: The name of the snippet that contains the list of filter option text.

Toggle [[]]

  • Filter label: Enter the label for the filter button.
  • Remember last-selected filter value: When a user returns to this page, Skuid will remember their previously-selected options.

Selecting Toggle as the Filter Type activates the Add Effect button. Each effect activates, activates and sets, or deactivates one particular condition. Stacking these effects allows for complex filtering through an easy-to-use on/off filter button.

Each effect includes the following properties:

  • Action: Activate or deactivate a model condition. This action works in relation to the condition’s state (Always On, Filterable Default On, Filtertable Default Off, Always Off).
    • Activate and Set Value: Activate and set the condition to a specific value.
    • Activate: Activate the condition. (Use for conditions with Always Off or Filterable Default Off states.)
    • De-Activate: Deactivate the condition. (Use for conditions with Always On or Filterable Default On states.)
  • Model Condition: The model condition to interact with.
  • Value: The value to set the condition to when using the Activate and Set Value option.

Use a JavaScript snippet as a filter option source

When using Select Option filters with Pick Options and Condition(s) set to Manually, builders can add an option source, one of which is a Snippet.

A custom filter option source snippet needs to return an array that can serve as a list of filter menu options to display in the filter.

Each of these filter options should be a JavaScript object with:

  • a label property, where “label” is the text to display to the user
  • a value property, where “value” is the actual value that (when a user selects this item) the filter will inject into the specified Model Condition to Affect.

For example, to have two filter options called Cheese and Pizza, create a filter source JavaScript snippet that looks like this:

1
2
3
4
var filterItems = [];
filterItems.push({ label: 'Cheese', value: 'cheese' });
filterItems.push({ label: 'Pizza', value: 'pizza' });
return filterItems;