How to :: create a date selector¶
Note
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.
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.
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:
- 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…)
Note that the from/until operators are inclusive, e.g. until “Today” will include today.
- Using fixed dates on a calendar:
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”:
- 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-26date.end
will be 2021-12-28
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:
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 <%= appRequesters.date %>
.
📖 Learn more on how to use this variable with the templating tutorial