How to :: create filters in code mode

Important

This is only available from the code mode

Overview

In each story you can configure different kinds of filters at different positions.

The way filters work is that they slice the input dataset to display only the subset rows of the dataset that match the criteria. This means your story will query all the data, but based on your filter selection, only a slice will be shown. This is different from the requesters that query only the selected slice from your data source.

Warning

The bottom-rigth filter configuration has to be specified OUTSIDE of the charts block. The two others have to be specified INSIDE the charts block. Please read carrefully the ‘Positionning filters’ chapter.

Configuration

To configure filters just add a filters object in you slide config. Depending the position of the filter you’ll have to include it inside charts or outside.

The filters object contain as keys the positioning. Three positions are available: bottom-right, upper-middle, upper-right.

The different configurations look like this:

filters:
  "bottom-right":
      on: "variable"
      type: "dropdown"
      datasets:["my_dataset"]

filters:
  "upper-right":
      on: "variable"
      type: "dropdown"
      datasets:["my_dataset"]

filters:
  "upper-middle":
      on: "variable"
      type: "dropdown"
      datasets:["my_dataset"]

Inside the filter configuration you have two mandatory keys to specify:

On

on : column name on which you will perform the filter. The filter values will be automatically computed from the unique values in this column.

With the following example it will display [revenue, margin, price] as the filter choices.

domain example :

label variable value
Lorem revenue 1
ipsum revenue 2
dolor revenue 3
sit amet margin 4
que j aime margin 1
faire margin 3
apprendre price 3
un nombre price 4
utile aux price 4

Type

type : The type of you filter. Four types of filters available are:

  • dropdown
dropdown

Note

When using dropdowns if you have empty lines in your column on wich you are filtering, you won’t be able to use the search functionality. Make sure to exclude them.

  • buttons

eval_rst .. figure:: images/buttons.png   :class: initial-width   :alt: buttons stars filter example ```

  • slider
slider
  • checkboxes
checkboxes

Datasets

datasets : Indicate on which dataset the filter will apply. Meaning in a double chart ou master/slave configuration, a filter can be used on 2 charts.

datasets:["my_dataset", "my_dataset_1"]

Positioning filters

Bottom-right

The filter will be displayed in the bottom right corner of the screen. Used as type buttons 90% of the time or slider otherwise.

⚠️ This position is outside the charts block, as only one can exist in each story ⚠️

title: "TITLE"
id: 34934
filters:
  "bottom-right":
    on: "variable"
    type: "slider"
    datasets:["my_dataset"]
charts: [
  chartType: "leaderboardCenteredAverage"
]

Upper-middle

The filter will be displayed just above the chart.

It’s configured inside a chart block, as one can exist per chart.

charts: [
  chartType: "linechart"
  filters:
    "upper-middle":
      on: "variable"
      type: "buttons"
      datasets:["my_dataset"]
]

Upper-right

The filter will be displayed just above the legend pane.

It’s configured inside a chart block, as one can exist per chart.

charts: [
  chartType: "linechart"
  filters:
    "upper-right":
      on: "variable"
      type: "buttons"
      datasets:["my_dataset"]
]

⚠️ If you have more than 2 filter’s options, make sure to use the dropdown type and not the button type for a better experience. You can go up to 3 filters choices as buttons if your filter’s labels are quite short.

Optional parameters

You have optional parameters too:

reset

reset : String label that will be displayed and available along with the other filter values extracted from the column. This reset value won’t perform any filter and the full dataset will be displayed. It’s like a “all” button.

dateFormat

dateFormat : (AVAILABLE ONLY FOR THE SLIDER) If you have transformed a column to a date (using data/date/selector and data/date/format), you can specify the output date format of your choosing. e.g ‘%Y-%m’ for ‘2015-12’. See this documentation for more details.

default

default : Specify which value shall be selected when the filter initializes.

A default selection of a filter can be defined in the configutation block of any filter. Use the “default” option as displayed below : (defaultSelected is a deprecated syntax. If you see uses of this legacy option, please use default as the defaultSelected option will be deactivated in future versions)

filters:
  "bottom-right":
    on: "variable"
    type: "buttons"
    default: "revenue"

The “revenue” variable will be the default selection when displaying the screen.

Specific checkboxes option

  • default/type : either ìnclude (all values specified in valueswill be selected by default) or exclude(all values specified in valueswill be un-selected by default)
  • default/values : list of values that will be selected (if type is include) or unselected (if type is exclude) by default

order

You can order the values of the filter by using a “custom” option :

filters:
  "bottom-right":
    on: "variable"
    type: "buttons"
    datasets:["my_dataset"]
    order:
      custom:[
        "revenue"
        "price"
        "margin"
      ]

alwaysSelected

Sometimes, it’s relevant to always keep one or several values unfiltered, like a reference.

Let’s say we want to display countries fitlered by continent but always keep the world value as a comparison:

continent country value
World World 65000000
Europe France 12000000
Europe Germany 3000000
Asia Japan 3000000
filters:
  "bottom-right":
    on: "country"
    datasets:["my_dataset"]
    type: "buttons"
    alwaysSelected: [ 'World' ]

When Europe will be selected, the following data will be used:

continent country value
World World 65000000
Europe France 12000000
Europe Germany 3000000

And for Asia:

continent country value
World World 65000000
Asia Japan 3000000

This can also be useful in maps to display zones that have no associated data, like in the following dataset:

brand floor value kpi
Brand A 1 100 surface
Brand A 1 20000 visits
Brand B 1 500 surface
Brand B 1 50000 visits
Brand C 2 25 surface
Brand C 2 12000 visits
Brand D 2    

With this filter, even if Brand D has no data, its associated zone will always be displayed on the map:

filters:
  "bottom-right":
    on: "kpi"
    type: "buttons"
    datasets:["my_dataset"]
    alwaysSelected: [ null ]