Filter Component Visual Guide

Introduction

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.

Getting Started

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.

Adding data: simple lists of options

Without data there is not much a filter can do. To populate the filter with a list of options, you can:

  1. Define a datasource a query and assign it to the component
  2. Fill in the property valuesArray, which is useful if you have a static dataset

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.

Limiting the number of selectable items

In some cases, the user should not be allowed to choose beyond a certain number of items. Here we set Selection Limit to 5.

Organizing options into groups

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:

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

If your data source has a different format, look into the "advanced options" of the reference page.

Always expanded

Sometimes it is best to keep the filters permanently expanded. Simply set the property Always Expanded to True.

Handling large list of options (CDA queries only)

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.

Pagination

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.

Server-side Search

You may be interested in delegating to the server the task of filtering the items. To do so, you will need to:

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.

Advanced configuration

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.

Using add-ins

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.

Changing default messages

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.

Showing values

In rare cases, it might be useful to show some extra information next to each item.

Example: Selecting a single item with an associated value

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.

Example: Multiple selection with associated values

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