Page Filter Basics

One of the important features of White Label Data is page filters. Page filters are inputs from the user, such as dropdowns and date pickers, that filter the results of visualizations. White Label Data allows you to connect page filters to individual visualizations without having to write any code.

When a page filter changes, the URL parameter associated with the page filter is updated and any visualizations that are subscribed to that page filter are automatically refreshed with new data.

Adding a Filter to a Page

A page filter is a type of visualization. You add a filter to a page in the same way you add any other visualization. See Adding Visualizations Using Tags. Filters are configured in the Config section of Layer files. A filter layer must specify the output filter configuration. Configuring the name of the URL parameter is necessary in order to allow filter widgets to be used and re-used multiple times on the same page with different URL parameters. Here is an example filter config in a Layer file:

<config>
{
    "type" : "simple-select-filter",
    "load_phase": 0,
    "filters" : {
        "output" : [
            {
                "name" : "dropdown",
                "urlparam" : "state"
            }
        ]
    }
}
</config>

In the above example, there is a set of named parameters for each filter, specified by the name attribute, that need to get mapped to a URL parameter. For a simple drop down filter, there is only one parameter that needs to be assigned a URL parameter, but a date range filter will have two parameters to map to URL parameters (one for the start and end dates).

Layers with filters can also have queries in them. You may want to query possible values for a drop down or query an initial date to set on a date filter. Like other visualizations, query results are mapped to attributes in the filter visualizations.

Subscribing to Filters

Any visualization that wants to be notified that a page filter has changed must configure itself to subscribe to input filter changes in its Layer config.

<config>
{
    "depends_on" : ["sv-indicator-template"],
    "load_phase": 1,
    "filters" : {
        "input" :
            [
                {
                	"urlparam" : "state",
                    "name" : "state_filter"
                }  
            ]
    }
}
</config>

The above example configures the visualization to be notified any time the URL params called state changes. When it does, the pipeline will be re-executed and the results re-mapped on the figure. The above config also specifies the name of the filter to use within the visualization. This name can be used as a parameter in queries. For example, you can put {{ state_filter }} in a WHERE clause (or in allowed_filters for Looker API queries) to filter results based on the page filter.

Load Phase

In the above example, you will note that the filter itself has a load_phase of 0, whereas the visualization that subscribes to it has a load_phase of 1. The feature allows for filters to load on a page prior to the rest of the visualizations. This is important because filters need to determine their current value before other visualizations make use of them. Currently, White Label Data supports only two phases, 0 and 1. Phase 1 does not begin until all visualizations on that page from phase 0 have completed.

Creating Custom Page Filter Widgets

While White Label Data includes built-in page filter widgets that are useful in most cases, you may want to create your own page filter widgets. Page filters can be created using custom visualizations. A page filter visualization is similar to a standard visualization in that it can fetch data using a query. It then connects the query results to input-based HTML markup. In addition, custom page filter widgets must implement required Javascript functions that handle changes to the inputs, update URL parameters, and notify White Label Data that filters have been changed.