🧞Advanced syntax for variables

What’s the difference between ‘{{ }}’ & ‘<%= %>’ syntaxes?

Variable values to be interpolated can be injected from 2 different sources:

• The user interface (front-end): these are variables that could be set by the App-builder and/or Viewer when editing the app configuration through the studio or when dealing with filters. These kinds of variables are injected by using the '<%= ... %>' syntax. This syntax is executed as Javascript code.

• Toucan's backend: these are variables coming from Toucan's instance configuration (for example instance name), or the user's attributes. These kind of variables are injected by using the {{ ... }} syntax.

Filters

In some configuration interfaces, you might need to use manually use our syntax to refer to a filter value, for a more advanced usage. This can be done with the syntax below (the FILTER_ID is accessible within the filter's configuration interface).

<%= filters["FILTER_ID"]["COLUMN_NAME"] %>

More detail on templating from the filter's value here.

All option in filters (__VOID__)

By default, the filters created are using the "All" option that allows to not apply the filtering. All option refers to the variable value "__VOID__" used as a kind of identifier to not apply the filter when the variable is used in YouPrep.

The case of date range filters

Date Range filters are special as when we choose the dataset's column, it's not from where we're fetching data. Also, as a range, it exposes a start and end date. Here's how to use them:

Start:

<%= filters["FILTER_ID"]["start"] %>

End:

<%= filters["FILTER_ID"]["end"] %>

Advanced use date of date filters

Variable from data range filters are expressed within ISO-8601 format with date and time as the following date: 2023-02-02T00:00:00.000Z

For different cases (data querying, display, ...), you might only need the date part (2023-02-02).

In order to extract the date part, you can use the templating syntax below (example for start date):

<%= filters["FILTER_ID"]["start"].toISOString().split('T')[0] %>

Advanced use case with management of __VOID__ in SQL

For some advanced use cases, when creating a dataset from a connector, you can make the choice to make some data transformation/filtering directly into SQL and refer to the variable with the syntax above. However, when the filter uses the option "All", the variable will take the value "__VOID__" that won't be interpreted by your database. Thus, you might condition the application of the filter.

Here is an example (where 4171d27a-f8dc-4c91-8c43-c750aa1eee95 is corresponding to the filter's ID, and company to the column name used by the filter) of a complete SQL query that includes WHERE conditions in order to filter the data.

SELECT * from my_table WHERE 
CASE
    WHEN <%= filters["4171d27a-f8dc-4c91-8c43-c750aa1eee95"]["company"] %> = '__VOID__' 
        THEN true
    ELSE
        company = <%= filters["4171d27a-f8dc-4c91-8c43-c750aa1eee95"]["company"] %>
END

Advanced use case with management of __VOID__ in storytelling

When being within the storytelling part, you can refer to the filter value (within narrative, section title, text tile, ...) in order to personalize the experience and facilitate informations interpretation. However the the actual selected value is corresponding to __VOID__ , you might want to display a more meaningful label. This can be done with the syntax below:

<%= filters["FILTER_ID"]["COLUMN_NAME"] === 'VOID' ? 'label_for_All' : filters["FILTER_ID"]["COLUMN_NAME"] %>

Advanced use case of list

Depending the the configuration of the filter, it can retrieve a list of values (for example the "checkbox" type) and not just one value. Thus in order to display the value in a customized way, the function join can be used in order to separate each value of the list by a custom char:

<%= filters["4171d27a-f8dc-4c91-8c43-c750aa1eee95"]["companies"].join(', ' ) %>

User attributes

At different configuration interfaces (connector settings, query setting, YouPrep, ...) you get to refer to user attributes, in order to personalize the experience depending on the user. In the example below, we refer to the user attribute named "database_name_attribute"?

{{ user.attributes.database_name_attribute }}

In some cases, we need to use a more complex syntax, in order to use a default value when the user attribute doesn't exist. In the example above, the syntax is referring to a user attribute named "database_name_attribute", and uses by default 'database_name_default' if the user attribute doesn't exist.

{{ (user or {}).get('attributes', {}).get('database_name_attribute', 'database_name_default') }}

Note that, if you want to display the value of a user attribute, within a narrative, tile, or home section title, you must use the <%= ... %> syntax like in the example (with country variable) below:

<%= user["attributes"]["country"] %>

Extra Variables

Extra Variables correspond to variables coming from an external environment (sent through Toucan SDK). You can refer to an extra variable by using the syntax below.

<%= extraVariables["my_variable"] %>

In some cases, we need to use a more complex syntax, in order to use a default value when the extraVariable doesn't exist within the context. In the example below, we refer to the extraVariable 'my_variable' if it exists, else we use by default the value 'my_default_value'.

<%= extraVariables["my_variable"] ?? 'my_default_value' %>

Language Variables

At different levels of the app (YouPrep, narrative, titles, ...), you can refer to language variables in order to personalize the end-user experience according the language preference. You can refer to a variable (defined in the dictionary of translation) with the syntax below:

<%= lang["ELEMENT_TO_TRANSLATE"] %>

You can also refer to the variable containing the value of the language preference with the syntax below:

<%= locale %>

More detail on language and translation here.

Chart Data

When being in a story, it's possible to refer to the first value of a specific column in the data used by the chart, for example in order to give contextualized data within your narrative. This can be done with the syntax below (knowing that the content between data brackets corresponds to the chart ID, which can be found in the chart configuration interface).

<$= data["4c7274d9-bae4-e77c-d1ef-21ddd98dee0c"]["my_column"] $>

However, when referring to a column resulting from an aggregation made through the SmartEditor, the column ("my_column") to which you have to refer to follows this format: __aggregType_myColumn__.

So for example, when referring to a column "profit" aggregated with the sum operator, the syntax to use will be:

<$= data["4c7274d9-bae4-e77c-d1ef-21ddd98dee0c"]["__sum_profit__"] $>

Here is the list of the different aggregation prefixes: sum (for sum), avg (for average), min (for minimum), max (for maximum), first (for first), last (for last), count (for count), count distinct (for Count Distinct).

More detail on chart dataset templating here.

User Group

At different configuration interfaces (connector settings, query setting, YouPrep, ...) you can refer to user attributes, in order to personalize the experience depending on the user. The example below shows how to call the variable through the back-templating syntax.

{{ user.groups }}

Note that, if you want to display the value of a user attribute, within a narrative, tile or home section title, you must use the <%= ... %> syntax like in the example (with country variable) below:

<%= user["groups"] %>

Syntax to use depending on the location:

• {{ ... }} : connector, connector query

• <%= ... %> : narrative, tiles

The user variable "groups" retrieves a list of values (groups)

Relative Dates

You can refer to relative dates defined automatically within Toucan. Here is the list of available variable.

• Today: <%= dates.today %>

• Yesterday: <%= dates.yesterday %>

• The actual week monday: <%= dates.thisWeekMonday %>

• The last week monday: <%= dates.lastWeekMonday %>

• The first day of the month: <%= dates.thisMonth %>

• The first day of the last month: <%= dates.lastMonth %>

• The first day of this quarter: <%= dates.thisQuarter %>

• The first day of the last quarter: <%= dates.lastQuarter %>

• The first day of this semester: <%= dates.thisSemester %>

• The first day of the last semester: <%= dates.lastSemester %>

• The first day of the year: <%= dates.thisYear %>

• The first day of the last year: <%= dates.lastYear %>

You can easily refer to those variables within YouPrep without using any syntax. More about it here.