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.
The main properties of the Filter Component are:
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"].
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
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
.
True
].
Set to True to enable the search box.
True
].
If set to True, an icon (checkbox or radio button) is shown next to each item.
False
].
Set to True to keep the filter permanently open.
"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.
False
].
Set to True if you want the filter to output the item labels instead of the ids.
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:
target
is null
.
target
is the DOM element associated with the root container, e.g. $('.filter-root-container')
.
target
is the DOM element associated with the root container, e.g. $('.filter-root-container')
.
target
is the DOM element associated with the root container, e.g. $('.filter-root-container')
.
target
is the DOM element associated with the group container, e.g. $('.filter-group-container')
.
target
is the DOM element associated with the item container, e.g. $('.filter-item-container')
.
target
is null
.
target
is null
.
There are also advanced properties, that allow further customization of the component:
{ /** * 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 } } }
The following example shows the expected data layout and demonstrates support for groups of options.
By default, the filter is expecting the columns in the folowing order: