How to :: use requesters in code mode

Overview

Requesters look like filters, except they don’t filter datasets after they are loaded. They modify the query to load only the subset of data that needs to be displayed, and rerun the query each time their selection changes.

Filters are great to quickly separate three of four categories in your data, but sometimes you would like to have a lot more choices, such as all the countries in the world or all the entities in your company.

For these particular needs, loading all the data for each choice and filter it afterwards is not an option, as the dataset would be way too large.

That is where requesters come in.

Configuration

requesters:
  "upper-right":
    query:
      domain: "domain_name"
    type: "dropdown"
    id: "requester_lovely_name"
    fields: ["country"]

Results

You can then use the requester’s value in your chart’s query:

datasets:
  'line-data':
      query:
        domain: "datasource1"
        country: "<%= requestersManager.requester_lovely_name %>"

This means the chart will only show data from the country selected by the user.

Types

Requesters types are similar to filters. Check this doc for more info

Warning

The checkboxes configuration is not available for requesters

Positioning

Requesters can be positionned in three differents places:

  • directly in the story: to request only the data needed for your viz
  • in the dashboard: to add a time dimension in your small-app
  • in the settings panel: for requesters applied to multiple stories

Requesters in stories

If too much data is loaded into a screen, you can use a requester that will select only the data you need.

To do so you need to:

  • create a requester in the story’s configuration block
  • modify your query in the story’s configuration block

Depending on the usine selected in the upper-right requester, the values loaded in the upper-middle filter will be different :

  • for usine 1 : Crit1 and Crit 3
  • for usine 2 : Crit2 and Crit 3

With a simple use of an upper-right filter instead of a requester, all the criteria would have been displayed into the upper-middle dropdown filter. And some filter combinations would not work.

Data source

line_ex criteria usine date_ex value_ex
France Crit1 Usine 1 2016 0.9
Allemagne Crit2 Usine 2 2016 1.2
France Crit3 Usine 1 2016 1
Allemagne Crit4 Usine 2 2016 0.7

Configuration

{
  level: 3
  title: "Requester illustration"
  parent_id:20
  id: 20000
  chartOptions:
    chartType: "linechart"
    data:
      query:
        domain: "domain_name"
        usine:"<%= requestersManager.requester_lovely_name %>"
      precision:
        value_ex:".0%"
    units:
      value_caisse:""
    value: "value_ex"
    groups: "lines_ex"
    date: "date_ex"
    requesters:
      "upper-right":
        query:
          domain: "domain_name"
        type: "dropdown"
        id: "requester_lovely_name"
        fields: ["usine"]
    filters:
      "upper-middle":
        on: "criteria"
        type: "dropdown"
    legend: true
}

Requesters in dashboard

Warning

This is not compatible with the new home

A date requester can be embedded at the top of the dashboard for a given report.

date selector

date selector

It will update the data when pressing the button.

Please note that :

  • first, you have to set up the date configuration in the report template
  • then, you need to add a requestersManager in your query in the dashboard template

Requester Configuration

Warning

In the report template (report.cson)

name: "Demo"
entityName: "{{ country }}"
id: "{{ index }}"
date:
  id: "date"
  type: "buttons"
  description: "Select another time period"
  query:
    domain: "ranks"
  fields: ["breakdown"]

Query Configuration

Warning

In the story (frontconfig.cson) or dashboard template (dashboard.cson)

domain “ranks”:

country value breakdown
France 15.3 Day
Allemagne 18.1 Day
France 19 YTD
Allemagne 15 YTD

Use the requestersManager in your query:

data:
  value:
    query:
      domain: "ranks"
      "country": "France"
      breakdown: "<%= requestersManager.date %>"
    field: "value"

Configuration Options

  • showInHeader:true/false set to true if you want this requester to appear in the header next to the report selector. Now you’ll be able to change the date of the report anywhere in the app
  • description:: if you want to change the default text displayed above the dropdown/buttons, add a description value
  • displayHumanFriendlyDates:: whether or not you want to let Toucan handle date formatting in date requesters. We will try to make date more human friendly and more mobile friendly. For instance if we detect “23/03/2019” we will display “23 January 2019”(desktop) or “23 Jan. 2019” (mobile). We strongly advised that you don’t switch off this option to false.

💡 Advice: If you have many dates available, you might want to display them in a dropdown instead of as a list of buttons. To do so, just set the type option to dropdown.

Advanced configuration: add roll-up/granularity

Let say you have a small-app looking at daily data, weekly data and monthly data.

You’d probably want the user to select first, his/her granularity: do I want to look at daily data or the monthly ones? Then, you’d want the user to select the date needed: a specific day or a specific month.

So if you have more dates, you might add a first step to your dropdown date selection by adding a granularity.

To do so, express the order of columns that user will use to select the date in the granularity option.

date level
06/08/2018 days
07/08/2018 days
August 2018 months
S2 2018 semesters
name: "Demo"
entityName: "{{ country }}"
id: "{{ index }}"
date:
  id: "date"
  showInHeader: true
  type: "dropdown"
  query:
    domain: "dates"
  label: "date"
  granularity: ["level", "date"] # All columns to sequentially choose the date

💡 Note: you can use as many columns as you need, e.g. to choose year, then month, then day.

Requester in Settings

Requesters are quite often used for Settings configuration when you want to use them in multiple stories. It won’t take space on the story and will remember the user’s setting across stories. Very useful!

Requester Configuration

Warning

In the frontconfig.cson, settings block

settings:
  requesters:[
    id:"toucan" # name of the requester that you will use in the slide config, it is mandatory and must be unique
    description: "Compare to" # sentence in the rolling list
    type:"dropdown" #see the filter page for available type of requesters
    query:
      domain:"example"
    fields:["column_1"] # name of the column containing the requesers' value
    slides:[31200,31201] # id of the stories the requesters should be available
  ]

Available options

  • default: default value set in the requester

Query configuration

Warning

In the story (frontconfig.cson) or dashboard template (dashboard.cson)

chartOptions:
      data:
        query:
          domain: "example"
          column_1: "<%= requestersManager.toucan%>"

You must put the requester id at the end of the requestersManager config so that it can load the data of the requester’s query.

Multiple Settings Requesters

Several requesters can be used in settings: requesters in settings

Configuration block :

requesters:[
  id: "segments"
  type: "dropdown"
  default: "Tous segments"
  query:
    domain: "available-segments"
  fields: ["column_ex"]
,
  id: "service"
  type: "dropdown"
  default: "Tous niveaux service"
  query:
    domain: "available-services"
  fields: ["column_ex"]
]

Tuto: reset option

When you use a requester in a query you do something like this country: "<%= requestersManager.country %>". It only queries data for the country selected. What if you also want a “All countries” ?

Easy peasy with the reset option.

Requester Configuration

In you requester config just add the parameter reset: "All countries" for example

Query Configuration

In your query, you need to integrate a if .. then .. else.. structure with the ternary operator .. ? .. : .. . When the requester value equals the reset value then the query should be equal to __VOID__. Internally Toucan Toco remove the query field if the value is __VOID__.

For example you have a requester for each country and you want to execute a query for all countries.

The adequete configuration will look like this.

domain: "sales"   country: "<%= requestersManager.country == 'All countries' ?  '__VOID__' : requestersManager.country%>"

It means that when the requester country will be equal to All countries then the query will look like this

domain: "sales"   country: "__VOID__"

Toucan will remove the field country and the query executed will be like this:

domain: "sales"

So you’ll be querying all the countries.

Otherwise if the requester country equals France, Toucan will execute the following query:

domain: "sales"   country: "France"

Tuto: complete object option

Sometimes you want to filter your data on a value that depends on the requester but that is not equal to the requester value displayed. For example, you have a requester displaying May 2018 but in your data you only have a date column with 05/2018.

To achieve this, specify completeObjectMode:true in your requester configuration.

This way you’ll be able to use: "<%= requestersManager.REQUESTER_ID.REQUESTER_PROPERTY %>" in your config.

Toucan keeps all the attributes of the object returned by the requester query, so you’ll be able to use them.

In our example if you have a domain available_dates like this

Data Sources

Domain “available_dates” :

month_year month year date
May 2018 5 2018 05/2018
June 2018 6 2018 06/2018
July 2018 7 2018 07/2018

Domain “sales” :

country value date
France 5 05/2018
France 6 06/2018
France 7 07/2018

Requester Configuration

All columns define in the fields parameter will be available for the queries.

id:"date"
type:"dropdown"
completeObjectMode: true
query:
  domain:"available_dates"
fields:["month_year", "month", "date", "year"]

Query Configuration

query:
  domain: "sales"
  year: "<%= requestersManager.date.year %>"

or

query:
  domain: "sales"
  date: "<%= requestersManager.date.date %>"

Tuto: “hardcoded” requester

If you already know which values your requester should take, you can avoid writing a query.

Just use the values properties instead.

The field option is therefore optional when only one attribute is provided.

requesters:[
  id: "timespan"
  type: "dropdown"
  default: "Weekly"
  values: [
    "Yearly"
    "Monthly"
    "Weekly"
  ]
,
  # Alternatively:
  id: "timespanShort"
  type: "dropdown"
  default: "Weekly"
  values: [
    label: "Yearly"
    short: "Y"
  ,
    label: "Monthly"
    short: "M"
  ,
    label: "Weekly"
    short: "Y"
  ]
  fields: ['label'] # label will be displayed, but short will also be available
  completeObjectMode: true
]

Tuto: change the type of a variable

When using a variable alone, its type is kept intact.

For example:

query:
  domain: "sales"
  year: "<%= requestersManager.year %>"

and the value of requestersManager.year is the number 2018, then it will be interpreted as

query:
  domain: "sales"
  year: 2018

Beware, if you use other characters surrounding your variables, the resulting type is always a string. For example year: "The incredible year <%= requestersManager.year %>" will become year: "The incredible year 2018".

If, in your data, the year appears as a string "2018" and not as a number, then you’d like to change the variable type to a string. This is possible by surrounding your variable by String(xxx): year: "<%= String(requestersManager.year) %>" will become year: "2018". Avoid this as much as possible, as it’s better to keep types consistent in variables and data.

Configuration

query:
  domain: "sales"
  year: "{{<%= requestersManager.year %> | number}}"

And it will be interpreted as

query:
  domain: "sales"
  year: 2018

So much magic !

Tuto: turn a requester’s value into stars

If you want to display a rate in the form of stars, you can use a special function that will be applied to the value of the requester.

Let’s say you want to display some percentage value (eg between 0 and 1) next to your tile’s title on your home page

For example

title: "Metric <%= requestersManager.rating %>"

will normally be interpreted as

someText: "Metric 0.3"

But you can use the stars function :

title: "Metric <%= stars(requestersManager.rating) %>"

Which will render :

stars filter example