Reading documentation is usually boring. It takes time and people are usually too busy to read things thoroughly. This is a visual guide to the filter component. Is also serves as a showcase of some of the options available in the component.
If you just added a new filter to the dashboard, assigned it an HtmlObject, and rendered your dashboard, this is what you get: a disabled filter.
Without data there is not much a filter can do. To populate the filter with a list of options, you can:
In the simplest approach, the first column contains the ID of the items, whereas the second column holds the label that will allow the user to identify the item. For instance, the following table and the two filters below are populated by the same data set.
Here, we created two filters that differ only
By default, both filter have filters (search boxes) enabled.
In some cases, the user should not be allowed to choose beyond a certain number of items. Here we set Selection Limit to 5.
The filter can also support groups of options. The grouping is automatically done for you if the data contains four or more columns. By default, the filter is expecting the columns in the folowing order:
If your data source has a different format, look into the "advanced options" of the reference page.
Sometimes it is best to keep the filters permanently expanded. Simply set the property Always Expanded to True.
By default, the filter attempts to load the entire dataset defined by a datasource. However, in some cases, the list of options might be quite large. If the datasource that populates the filter with data is a CDA query, you may want to take advantage of CDA's support for pagination and server-side search.
You can configure the filter to sequentially load pages of items from the server.
Then, as you scroll down the list, the filter loads more data from the server
and updates the list of visible items.
You will typically need to:
When the user reaches the bottom of the scrollbar, a new page is loaded and added to the list of items.
You may be interested in delegating to the server the task of filtering the items. To do so, you will need to:
SELECT optionID,optionLabel FROM myTable
WHERE optionLabel LIKE '${searchBox}';
component: {
search: {
serverSide: true
}
}
Whenever the scrollbar reaches the bottom (or the top, for that matter), a new page is requested to the server, and more items are added to the filter.
CDE only exposes the most relevant options, the one that are most likely to be used.
Specific dashboards may have custom requirements, some of which can even be dynamic.
Just because there is no visual way of defining a behaviour, it does not mean it cannot be done.
To modify or extend the default behaviour of the filter, you can:
For more information, look into the filter reference page.
Keep on reading for some examples of advanced configurations.
An add-in is basically a snippet of code wrapped in a reusable way that modifies the component. Below, we used the addIns "randomColor" and "template" to the slot "renderItemSelection".
You can customize the addIn options programmatically via the setAddInOptions
method of the component:
function preExecution(){
this.setAddInOptions('renderItemSelection', 'template', {
template: '<a href="http://en.wikipedia.org/w/index.php?search={{label}}" target="_blank">{{{label}}}</a>',
filter: '.filter-item-value',
postRender: function($tgt, st, opt){
$tgt
.find('.filter-item-value a')
.click(function(event){
event.stopPropagation();
});
}
});
}
For more information on filter add-ins, please consult the component's reference page.
As you saw above, if a filter has no options to show, it simply displays a message "Unavailable". While generic enough, this message may not be suitable for your dashboard:
Your business may require a different message, perhaps because it serves users that do not speak English.
One mechanism is to create a file messages_${locale}.properties next to the component
filter_Root_isDisabled = Not Available
...
You can also customize the messages on a per-component basis via the "Advanced options" property:
function options(){
return {
component:{
Root: {
strings:{
isDisabled: 'No available data'
}
}
}
};
}
For a list of the strings used by the filter, please consult the component's reference page.
In rare cases, it might be useful to show some extra information next to each item.
In the example below, each item is associated with a value. Under Advanced Options we enabled showing of values:
function options(){ return { component: { Item: { options: { showValue: true } } } }; }
We also assigned the sortByValue addIn to the sortItem addIn slot, so that the items are sorted by decreasing value.
In the next example, we can take the customization to the next level, by automatically adding the values of the selected items.
Under Advanced Options we enabled showing of values for all levels:
function options(){ return { component: { Root: { options: { showValue: true } }, Group: { options: { showValue: true } }, Item: { options: { showValue: true } } } }; }
As before, we assigned the sortByValue addIn to the sortItem addIn slot. Also, we assigned the sumValues addIn to add-in slots renderRootSelection, renderGroupSelection and renderItemSelection