How to :: Use templating variables in your application

What is templating?

As a data story teller, you’re probably familiar with these questions:

  • Can I customize my commentary based on what report/view I’m choosing?
  • Can the chart display different metrics/values based on the user choice?
  • How can I use the view I created and only show a slice of the data?
  • Can the value shown be different based on what the user selects?
  • Can I use the result of a query in my commentary?

The answer to all of these questions is : TEMPLATING.

There are 2 different templating syntaxes, that are used for different purposes:

  • Display data from a dataset anywhere in your story
  • Display data from a requester’s selection

Display data from a dataset anywhere in your story

Adapt the context elements of your stories

💡 Did you know you can re-use results of your queries in your story?

For example, in the:

  • commentary
  • sources
  • reco
  • etc..

Just “call” the data coming from your dataset in the story, by using the Dollar syntax ``<$= $>``

The Dollar syntax <$= $>

The templating dollar syntax is used when you want to adapt a value that depends specifically on the screen / widget you are working on (so any local information).

It can refer to any column of the used dataset, or to any declared value in your query.

<$= my_dataset.my_column $>

Display data from a requester’s selection

Overview

There are 3 types of requesters:

  • appRequesters: date and view/report selector
  • requesters in stories
  • requesters in settings (not supported by the studio yet)

The requester can be used to query a specific substet of data or it can be use in all the context elements of your story by displaying the value selected in your:

  • sources
  • commentaries
  • recommendations

The Percentage syntax <%= %>

To use the result of a requester, you need to use percentage syntax

The percentage syntax can be used everywhere : dashboard, stories, postprocess, etc. This syntax will simply be replaced by a string after it has been interpreted.

📝 For example, if I’m on the France view, the result of <%= appRequesters.report %> is france

On the contrary of the dollar syntax, it concerns any global information of the app (so basically any requester). So requesters you create on a story or appRequesters(for the view and date of the whole app).

Note

This syntax replaces your templating with a string value by default.

Learn more about the different types of requesters

Learn more about the view requester

If you have created a view, you may want to use it to filter the data you’re showing.

📝 In this example, I want the France view to only have access to France data. As the french manager I will only get access to the revenue trend of France

By creating views, you have generated variables that can be used anywhere in your app. Tiles, stories, widget, asset customization, source, commentary etc…

This variable can be used with the parameter <%= appRequesters.report %>.

📝 In this example, if I’m on the France view, the result of <%= appRequesters.report %> is france

⚠️ The result of the variable is coming from the view datasource you have defined earlier. Pay attention to spelling, caps and trailling space. This result should match exatcly the view’s datasource and other datasources you will match with it.

This parameter can be used in the dataset editor to customize your dataset and create specific queries.

This variable should be applied to a column from your tile datasource that contains a way to identify data specificly for your user’s view.

view requester

view requester

Lean more about the date requester

If you have created a date selector, you may want to use it to filter the data you’re showing.

📝 In this example, if I select January, I only want to display January’s data

By creating a date selector, you have generated a date variable that can be used anywhere in your app. Tiles, stories, widget, asset customization, source, commentary etc…

This variable can be used with the parameter <%= appRequesters.date %>.

📝 In this example, if I’m on the January view, the result of <%= appRequesters.date %> is January

⚠️ The result of the variable is coming from the date datasource you have defined earlier. Pay attention to the date format! This result should match exatcly the view’s datasource and other datasources you will match with it.

This parameter can be used in the dataset editor to customize your dataset and create specific queries.

This variable should be applied to a column from your tile’s datasource that contains a way to identify data specificly for your user’s date selection.

Learn more about the story requester

If you have created a requester, you may want to use it to filter the data you’re showing.

This variable can be used with the parameter <%= requestersManager.lovely_name.column %>.

lovely_name is the id you have filled while creating the requester.

id requester

id requester

Use cases of templating

Using basic templating with requesters

You might want your charts to display values depending on what is selected in the screens’ requesters or in your appRequesters (see documentation on requesters [here] (https://docs.toucantoco.com/concepteur/tutorials/custom-data-storytelling/02-requesters-vs-filters.html#slice-data-with-a-requester) and on appRequesters (view and date report selectors) [here] (https://docs.toucantoco.com/concepteur/tutorials/custom-data-storytelling/01-view.html) ).

You will want to use in this case the percentage syntax.

The information you need to gather is the name of your appRequester, and the name of the column of your dataset in which are displayed the values of your appRequester. This is the syntax you will use in your datasets block:

For regular requesters: nameofyourcolumn: <%= requestersManager.requestersname %>

For appRequesters: nameofyourcolumn: <%= appRequesters.report %> (view requester) nameofyourcolumn: <%= appRequesters.date %> (date requester)

Example :

coffeescript     datasets:       my_dataset:         query: [             $match:               domain: "source"               date: "<%= appRequesters.date %>"               metric: "<%= requestersManager.metric %>"         ]

Using templating with integer value

The value returned by a requester is a type string by default. But you can overwrite this and return an int using the following syntax:

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

Using templating with conditions

If you need to add one or several conditions to your templating, you will want add an « if… then… else » syntax, represented by ‘?’ and ‘:’

Example with one condition :

coffeescript     datasets:       my_dataset:         query: [             $match:                 domain: "source"                 geozone: "<%= appRequesters.Group == 'Region' ? ‘region' : ‘country' %>"         ]

Example with several conditions :

coffeescript     datasets:       my_dataset:         query: [           $match:               domain: "<%= appRequesters.report.group == 'Region' ? ‘region_dataset' : appRequesters.report.group == ‘Country' ? 'country_dataset' : ‘city_dataset' %>"         ]

What this line literally means : If the group of my view selected equals ‘Region’, then use ‘region_dataset’ as domain, or else if the group of my view selected is ‘Country’, then use ‘country_dataset’. If neither of these conditions is true, then use ‘city_dataset’

Using the __VOID__ attribute

You might want to filter your dataset with templating only for specific values of one of your requesters. When your filtering line with templating will not be relevant : you will have to use the VOID syntax. Under the ‘VOID’ condition, the filtering line will not be interpreted. One of the most common examples why you might need to use this syntax is when your requesters’ value is equal to the reset value.

📝 For example, you have a requester with countries ; when on a specific country view, you want to filter your data on that country. For the view « all countries », you don’t want to filter your dataset.

coffeescript   datasets:     my_dataset:       query: [           $match:               domain: "source"               country: "<%= requestersManager.country == ‘All countries’ ? ‘__VOID__’ : requestersManager.country %>"       ]

What this line literally means is : when my ‘country’ requester is equal to ‘All countries’ then the query is :

coffeescript   datasets:     my_dataset:       query: [           $match:               domain: "source"               country: "’__VOID__’"       ]

It will therefore only be interpreted as :

coffeescript     datasets:       my_dataset:         query: [             $match:                 domain: "source"         ] … All countries are kept !

Using templating both sides of « : » in your queries

Sometimes, you may need to use templating also on the “left side” of the « : » delimiter of the filtering line in your query. The syntax will be exactly the same on both sides.

Example :

coffeescript       "<%= appRequesters.report.group == 'Region' ? 'region' :  appRequesters.report.group == ‘Country' ? ‘country' :       ‘city’ %>" : "<%= appRequesters.report %>"

What this line literally means : If my group of views selected equals ‘Region’, then use the column ‘region’ of my dataset and filter it on the name of the view selected.

Or else if my group of views selected is ‘Country’, then use the column ‘country’ of my dataset and filter on the name of the view selected.

If neither of these conditions is true, then the column ‘city’ of my dataset and filter on the name of the view selected.

Using templating in postprocess formulas

You can also use the templating syntax directly in your postprocess functions ! The result inbetween the percentage syntax will be interpreted as text in the parameters of a postprocess function as well.

Example: coffeescript       postprocess: [         {           formula:             new_column: "sum"             formula: "<%= requestersManager.requester_first_column_name_to_sum %> + second_column_name_to_sum"         }       ] What this line literally means : sum two columns, the first name of the column to sum is defined by a requester I created in my story and the second is a fixed column from my dataset

Using templating with complete ObjectModeTrue

Turning the completeObjectMode option of your requester to true will allow your to use multiple columns from your report dataset. You will have to add the name of the column you want to use to your templating.

For example:

for the countries column : countries: <%= appRequesters.report.countries %> or for the zones column :zones: <%= appRequesters.report.zones %> or for the date groups column :date: "<%= appRequesters.date.groups %>"

It is very convenient when you want to use one column with displayed values (nicely written values) and one column with filtering values (not as nicely written but easier to write)

For example : you might want your user to click on a “Evolution” button but to filter the dataset on the column named “evo”, which is shorter to write. You could also use this syntax to filter your dataset on the previous date to the one selected in the date requester like this :

datasets:
  my_dataset:
    query: [
        $match:
            domain: "source"
            date: $in:["<%= appRequesters.date.current_date %>","<%= appRequesters.date.previous_date %>"]
    ]
What thus line mean : filter the date column to make it either the current date or the previous to current date.

Need more? Let us know!