Filter Component Reference

Introduction

A filter is a central component in a dashboard. Traditionally represented as a drop-down list, it is typically used as a means to quickly filter information.

In CDE, the list of selected items is usually stored in a dashboard parameter. Whenever the filter is updated, the parameter is read and the items in that list are marked as selected. When the user changes the selection, the parameter is updated.

Quick Reference (for the impatient)

The main properties of the Filter Component are:

Title
Label on top of the filter
Parameter
Parameter []

Name of the parameter that stores the selection state.

The filter reads from the parameter when the component renders, and writes to the parameter whenever the user chooses to commit the selection state. In single-select mode, the commit is automatic, whereas in multi-select mode the user must first click on the "Apply" button

The parameter is written as an array of ID's, so for a selection of "Foo" + "Bar", the parameter will have ["Foo", "Bar"]. In the case where only one selection is made, the array will have one element, ex. ["Foo"].

Multi Select
Boolean [False].

By default, it is set to False, the filter only allows the selection of single items. If set to true, multiple items can be selected, up to the number specified by the property Selection Limit

Selection Limit
Integer [2000]

Limits the number of item that can be selected. This property acts globally, in the sense that it does not matter which group the option belongs to. Only active when multiselect is True.

Show Filter
Boolean [True].

Set to True to enable the search box.

Show Icons
Boolean [True].

If set to True, an icon (checkbox or radio button) is shown next to each item.

Always Expanded
Boolean [False].

Set to True to keep the filter permanently open.

Output Type
Enum {"Item Ids" | "Group and Item Ids"} ["Item Ids"]

Determines how the selection is written to the parameter upon commit. If set to "Group and Item Ids", the filter attemps to use groups Ids when all of its members are selected, which results in a more compact result.

Value as id
Boolean [False].

Set to True if you want the filter to output the item labels instead of the ids.

Add-Ins

The default behaviour of the component can be customized by associating a list of add-ins to each slot. The signature of the add-ins is function (target, state, options), where state contains two fields, model and configuration.

The available slots are:

postUpdate
Runs when data is added to model. target is null.
renderRootHeader
Runs on every update of the Root header (the part of filter that remains visible when the filter is collapsed). target is the DOM element associated with the root container, e.g. $('.filter-root-container').
renderRootSelection
Runs when the selection changes. target is the DOM element associated with the root container, e.g. $('.filter-root-container').
renderRootFooter
Runs when the Root footer is updated (e.g. notifications). target is the DOM element associated with the root container, e.g. $('.filter-root-container').
renderGroupSelection
Runs when the selection changes. target is the DOM element associated with the group container, e.g. $('.filter-group-container').
renderItemSelection
Runs when the selection changes. target is the DOM element associated with the item container, e.g. $('.filter-item-container').
sortGroup
Determines the visual order of the groups of items, must return a value (string or number). target is null.
sortItem
Determines the visual order of the items, must return a value (string or number). target is null.

Advanced properties

There are also advanced properties, that allow further customization of the component:

Advanced Options
Function that returns a javascript object. Possible properties:
{

    /**
     * Properties associated with importing data into the model
     */
    input: {
      indexes: { // Column indexes of the different fields (0-based)
        id: 0,           // Id is a string that identifies an item uniquely
        label: 1,        // Label is the text associated with an item
        parentId: 2,     // If the item belongs to a group of options, this is the id of the group
        parentLabel: 3,  // Label of the group to which the item belongs to.
        value: undefined // Secondary bit of text that will be show next to the item label
      },
      defaultModel: { // Default properties of the model
        isDisabled: true
      },
      root: {
        id: undefined // Overrides the id of the root.
      }
    },


    /**
     * Properties associated with exporting the state of the model to a parameter
     */
    output: {
      outputFormat: 'lowestId'  // equivalent to setting Output Type option to "Item Ids" in CDE
                                // 'highestId' is equivalent to picking "Group and Item Ids" in CDE
                                // It is also possible to assign a custom function there
    },


    /**
     * Configuration the response of the component to its environment
     */
    component: {
      pagination: {
        pageSize: Infinity // An integer sets the number of items per page. Infinity disables pagination.
      },
      search: {
        serverSide: false // Set to true only if your queries accept a search parameter
      },
      selectionStrategy: {  // Interaction logic. What actions should occur when I click on an item
        type: 'LimitedSelect', // 'SingleSelect' or 'LimitedSelect'
        limit: 500 // sets the maximum number of options that can be selected
      },

      /**
       * Configuration of the Root View
       */
      Root: {
        options: {
          styles: [], // array containing a list of CSS classes to be added to the root container
          showCommitButtons: true,   // show/hide Apply/Cancel Buttons
          showFilter: false,         // show/hide filter box
          showGroupSelection: true,  // show/hide All
          showButtonOnlyThis: false,
          showSelectedItems: false,  // optionally display the labels of selected items
          showNumberOfSelectedItems: true,
          showValue: false,         // optionally shows the value associated with the root
          scrollThreshold: 12, // number of children (items or groups) that triggers a scrollbar
          useOverlay: true, // should the filter display an overlay when expanded?
          expandMode: 'absolute' // 'relative' will push content on expand, 'absolute' will not
        },
        strings: {
          title: '',            // overrides Title property
          isDisabled: 'Unavailable', // message displayed when the filter is disabled
          allItems: 'All', // message displayed when all items are selected
          noItems: 'None', // message displayed when no items are selected
          btnApply: 'Apply', // label of the Apply button
          btnCancel: 'Cancel'  // label of the Cancel button
        },
        view: {
          overlaySimulateClick: true, // when clicking on the overlay, should the click
                                      // be delegated to the element underneath?
          scrollbar: {
            engine: 'mCustomScrollbar', // also 'optiscroll'
            options: { //engine-specific options
              theme: 'dark',
              alwaysTriggerOffsets: false,
              onTotalScrollOffset: 100
            }
          }
        }
      },

      /**
       * Configuration of the Group View
       */
      Group: {
        options: {
          showFilter: false,
          showCommitButtons: false,
          showGroupSelection: false,
          showButtonOnlyThis: false,
          showButtonCollapse: false, // show/hide button that allows collapsing of groups
          showValue: false, // optionally shows the value associated with the group
          scrollThreshold: Infinity // number of items in the group that triggers a group-only scrollbar
        },
        strings: { // Same keys than Root, but used in the context of a Group
          allItems: 'All',
          noItems: 'None',
          btnApply: 'Apply',
          btnCancel: 'Cancel'
        }
      },

      /**
       * Configuration of the Item View
       */
      Item: {
        options: {
          showButtonOnlyThis: false, //show/hide "Only This" button
          showValue: false // optionally shows the value associated with the item
        },
        strings: {
          btnOnlyThis: 'Only' // caption of the "Only this" button
        }
    }
}
        

Example

The following example shows the expected data layout and demonstrates support for groups of options.

Expected data layout

By default, the filter is expecting the columns in the folowing order:

  1. Item Id
  2. Item Label
  3. Group Id
  4. Group Label