Setting Filter and Parameters Prior to Load using JavaScript API

Today I took a look at the updated Tableau JavaScript API documentation just for a quick reminder of some syntax, and noticed something I’d never seen before on this page.

“Academic Year” : “” … that seems to be a field name. I changed mine to see if I could set individual values:

options = {
hideTabs: true,
"Gender": "Men",
"College" : ["Arts & Sciences", "Communication"],
"YEAR([Date])" : [2009, 2010],
onFirstInteractive: function () {
console.log("Run this code when the viz has finished loading.");

and sure enough it worked. I’ve tested on 9.1, 9.2 and 9.3. Russell Christopher assures me this has always been possible, just never been documented. This means you can set the values for a filter prior to load, rather than loading the viz and then applying a FilterAsync action, which requires a reload. If you are setting the values of filters programmatically at load time, this could greatly improve your overall load times.

I’ve tested with Parameters as well — the same syntax works. I’m sure that as with URL parameters, you need your Tableau Parameter names to be distinct from any Field Names, otherwise Tableau will apply your value to filter the Field rather than changing the parameter. You can’t yet set continuous or relative date filters this way, but if you use parameters to make the date filter start and end dates, you can set the parameter values prior to load using this technique.

Note on Security: This mechanism is actually just a fast translation method to the existing URL parameters for filters and Tableau Parameters. It has all of the same limitations and definitely passes all the values across in the URL string of the GET request. So don’t ever use it to pass any values that should be secured or hidden.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s