How to :: create a date selector


This is optional, you can chose to not have any custom date selector available for your users.

What is a date selector?

You can consider the date selector as a dedicated filter on time. At Toucan we consider dates to be a critical axis to storytell your data, while other BI tools deal with it just as a dimension among others.

A date selector is a way for the user to choose a specific time period for which the data will be shown.

Once configured, this selector then can be tied to any visual element of the App: tiles on the home page, charts and highlighted KPIs in the stories.

When the selector is tied with those elements, the user will be able to filter the dates visible throughout the app by selecting specific dates, date ranges, or even preset dates.

The date selector can be visible from the home and from the stories.

📝 This documentation will focus on how to configure a date selector in a few clicks.

Add a date selector

Since we see that time is used in almost every App of our clients we have decided to make the date selector configuration very easy for you.

When you are in “staging mode”, you will see “+ Add date selector” on top of your screen.

Add date selector button

Overview of the configuration interface

For App Builders, the date selector configuration consists in a module split in two parts:

  • On the left, the configuration panel: you will use it to configure “Period types”, “Date limits”, “Custom Periods” and “Default Selection”
  • On the right, you will see the preview of the configuration made on the left. The date selector will appear as if an end user was seeing it.
Date Selector Configuration

Configuring Period Types

You can select all the period types relevant to your app’s storytelling needs.

By default, you will see only days. You can also enable and disable:

  • Days
  • Weeks
  • Months
  • Quarters
  • Years

Each of these period types comes with formatting options.

Note that the format and language depends on your app language - for now, only French and English are available.

Configuring Date Limits

Date limits represent the bounds of the selectable dates. Configuring “date limits” will limit the visibility of the calendar for an End User selecting dates and date ranges.

Let’s say you have 5 years of history and you want to limit your user selection to the last 3 years. You can setup the date limits so users will only be able to select dates within the last 3 years.

You can configure date limits through different methods:

  • Using preset date ranges (that we have prepared for you). You will see them appearing on the left of the “Date Limit” configuration panel:
List of presets for the date limit configuration
  • Using relative dates: define an interval from/until a reference date. Do this by selecting a number, a period type, from/until and a reference date (today, yesterday…)
Date limit configuration: relative dates

Note that the from/until operators are inclusive, e.g. until “Today” will include today.

  • Using fixed dates on a calendar:
Date limit configuration: fixed dates

Note that currently you can only have multiple selections in the “Days” tab.

Configuring Custom Periods

“Custom periods” are a nice way for you to add pre-selected date ranges that are relevant to your business.

Let’s say you are working in retail: you can create a date range called “Black Friday 21”, that users will be able to select easily.

  • To do so, you can click on “Add custom range”:
Custom Period configuration
  • Give a name to your custom range and configure it by using “Preset Dates”, “Relative dates” or “Fixed Dates” (this is the same user experience as in “Date Limits”, see above).

You can also delete (clicking on the bin icon) or modify (clicking on the “+” icon) already set custom periods.

Configuring a Default Value

The default value is the default selection appearing when users log in the app for the first time. The default value is also displayed when users empty the selection they made.

As an App Builder you will be able to select between custom periods (see above), or preset values that we have picked for you.

You can check the video in the “Custom Periods” paragraph to see how to configure this.

Use the date selector in your application

Now that you have configured a date selector, you can link it to your tiles, highlighted KPIs and stories. Dates selected by users will be represented as variables that you can use to filter data.

You can do this while editing your data in YouPrep:

  • Add a filter step (“Keep rows”)
  • Select your date column and include a condition (such as “is greater than or equal to” or “is less than or equal to”)
  • select the variables “date.start” and “date.end” by clicking on the curly brackets “{}”, those variables come from the date selector start and end dates

Ex: When a user selects “Black Friday 21”, that you have configured to be from Friday, 26th of december 2021 to Sunday, 28th of december 2021 in your date selector:

  • date.start will be 2021-12-26
  • date.end will be 2021-12-28
Use the date selector in your data

Switching to “the dataset based” date selector

If you have an advanced use case that isn’t covered by our simple date selector, you can switch to the advanced interface.

The advanced interface allows you to create your own date selector based on a dataset containing date columns. You can use our YouPrep module (previously called “Visual Query Builder”) to prepare such a dataset.

To switch to this mode click on the “Need more customization? Use a dataset instead” link at the bottom right corner:

Switch to advanced

How to configure a “dataset based” date selector

Select the dataset containing your list of dates and configure the date selector.

📝 In this example, we want to have a monthly overview of our sales, and a quarter selection. So I want a dropdown menu where I can select “January” or “February” or “Q1”.

Configure granularity

Let say your users have access to February data. This data is computed for the current month, but also cumulated, and for 2019, 2018, etc…

This complex drill in the data can be easily done with the Granularity option.

Configure the granularity option to activate a nice built-in UX for your users. They’ll be able to select a first level of dates and then select from there a specific date.

The granularity feature accepts many levels, but try not to make it too confusing for your users.

Use the advanced “dataset based” date selector

The date selector creates a variable that can be used almost anywhere in the app with the parameter <%= %>.

📖 Learn more on how to use this variable with the templating tutorial