Tutorial

Update a date filter to a specific range

Difficulty level

Intermediate

Programming languages

JavaScript, HTML

Keshia Rose

Product Manager, Tableau

This tutorial will show you how to set up an extension that will automatically update a date range filter to a lower bound of one year ago, and an upper bound of right now. Extensions are a way to embed web applications into Tableau dashboards that allow you to extend the features or Tableau and integrate with other applications.

Set up your environment

In this mini project, we will be utilizing Glitch as our text editor and hosting service.

Create your own copy of the starter project by remixing it.
To keep your project and make all your projects easy to find later click Sign In to create an account.
Click on the Show link at the top then click In New Window to go to your project page.
Copy the URL on that page, it should look something like: https://substantial-girl.glitch.me/.
Close the live preview page and go back to the editor. Click on MyAwesomeExtension.trex to open it. Change YOUR URL HERE to the URL you copied in the last step.
Download the MyAwesomeExtension.trex file by editing and pasting the below link into your browser window. <YOUR URL HERE>/MyAwesomeExtension.trex. The file should download into your downloads folder.

Start Desktop in debug mode

Windows

Exit Tableau if it is already running on your computer.
Open a Command Prompt window.
Start Tableau using the following command. Replace with the version of Tableau you are using (for example, Tableau 2019.1).

"C:\Program Files\Tableau\Tableau <version>\bin\tableau.exe" --remote-debugging-port=8696

Mac

Open a Terminal window.
Start Tableau using the following command. Replace with the version of Tableau you are using (for example,2019.1.app).

open /Applications/Tableau\ Desktop\ <version>.app --args --remote-debugging-port=8696

Test your extension

Download and open DateRange.twbx in the Desktop instance you just opened with the debugger. (File > Open, not just double click)
Drag and drop a new Extension object (bottom left pane) to the bottom of your dashboard.
Allow the extension to run.
Confirm that you see "This is an extension!".
Go back to Glitch and change "This is an extension!" to a different phrase.
Reload your extension and make sure you see your phrase in Tableau.

Start coding!

In Glitch, go to your index.html file and before the </head> line, add a line to reference the Tableau Extensions API library:

<script src="https://cdn.jsdelivr.net/gh/tableau/extensions-api/lib/tableau.extensions.1.latest.js"></script>

Next, go to the script.js file (which is already referenced in index.html) and add the following to initialize your extension:

tableau.extensions.initializeAsynch().then(() => {
  console.log('I have been initialized!!')
});

Wait! Let's use the debugger

In your browser, go to the debugging homepage (http://localhost:8696).
Note: This will not work if you are using Chrome version 80 or higher. It will also not work if you are on Tableau Desktop 2018.3 or lower. If either of these is the case, please follow the instructions here to download the Chromium browser for debugging.
Click on your extension in the browser (should be named "My Awesome Extension").
If it's not already selected, click the Console tab at the top to open the console.
Notice we're getting an error saying Uncaught TypeError: tableau.extensions.initializeAsynch is not a function at script.js:1. Looks like there is a typo in our call to initialize. Remove the 'h' from the end of the function call initializeAsynch -> initializeAsync in script.js.

tableau.extensions.initializeAsync().then(() => {
  console.log('I have been initialized!!')
});

Reload the extension in Tableau by clicking the down arrow on the extension zone and selecting Reload from the menu.
In your browser with the debugger, go to http://localhost:8696 again and click on My Awesome Extension. (Note you must reload the page, hitting back alone will not reset the console)
You should now see the message "I have been initialized!!" in the console. Use this console to test and debug your extension as you work.

Automatically set a date range filter.

Our goal in this section will be to set the date range filter to a lower bound of one year ago, and an upper bound of today.

Make sure you have the latest data to work with by refreshing the extract. Data > Historical AMZN Data > Extract > Refresh
Note: You will not see the latest data in the viz until you adjust the filter.
Before we begin, familiarize yourself with the Extensions API Reference. All filter-setting functions stem from worksheet objects. We will be using applyRangeFilterAsync() in this example to change the filter.
Notice that applyRangeFilterAsync() takes two parameters:
- fieldName: this takes a string of the field you want to filter.
- filterOptions: this takes a RangeFilterOptions object. This object takes the optional min, max, and nullOption parameters.
Since applyRangeFilterAsync() is a method on a worksheet we first have to get a worksheet to call it on. But to get the worksheet, first, we have to get the dashboard. After initializing we can get access to the dashboard by adding the following line into the .then() block replacing the console log: let dashboard = tableau.extensions.dashboardContent.dashboard;
Then from there, we can get the desired worksheet by adding the following line next: let selectedWorksheet = dashboard.worksheets.find(w => w.name === 'Historical Trend');. Here we're using the find() function to choose a specific worksheet. Note: Try console logging dashboard and worksheet to see their structure.
At this point your script.js file should look something like this:

tableau.extensions.initializeAsync().then(() => {
    let dashboard = tableau.extensions.dashboardContent.dashboard;
    let selectedWorksheet = dashboard.worksheets.find(w => w.name === 'Historical Trend');
});

Let's add a function to do the work of getting the right dates and setting the filter. Below the entire initialize function add a new function:

function updateFilterRange(worksheet, fieldName) {

}

Note: our new function takes two parameters of it's own, worksheet and fieldName. 8. Inside this method we will get today's date & subtract a year from it for our minimum.

let today = new Date();
let lastYear = new Date();
lastYear.setFullYear(today.getFullYear()-1);

Now that we have the two dates we need for our min and max parameters (nullOption is optional) we can use applyRangeFilterAsync(): worksheet.applyRangeFilterAsync(fieldName, { min: lastYear, max: today});
At this point your script.js file should look something like this:

tableau.extensions.initializeAsync().then(() => {
    let dashboard = tableau.extensions.dashboardContent.dashboard;
    let selectedWorksheet = dashboard.worksheets.find(w => w.name === 'Historical Trend');
});

function updateFilterRange(worksheet, fieldName) {
    let today = new Date();
    let lastYear = new Date();
    lastYear.setFullYear(today.getFullYear()-1);
    worksheet.applyRangeFilterAsync(fieldName, { min: lastYear, max: today});
}

Now that we have our function, let's call it when we initialize. Add the following into your initialize function:

let fieldName = 'Date';
updateFilterRange(selectedWorksheet, fieldName);

Finally, your script.js file should look like this:

Test your extension by setting the date range filter to month range and then reload your extension. Notice the range filter changes to a lower bound of one year ago, and an upper bound of today and the viz updates.

Challenge exercises

Now that you know the basics of updating date range filters, try implementing the following bonus challenges.

Add a filter for the closing price and automatically update it to a certain range.
Set the filter to one week ago or one month ago.
Add buttons that set the date to specific ranges, like YTD, last week etc.
Use two parameters for the range.

Last updated: 10 September, 2021

Developer Programme portal