How To – Tableau Javascript API for Dummies. Vol 2: auto-refresh with a twist.

After the first not-really-diving into the API, let’s start working with something relatively easy: embed a viz that will self-refresh. Only to make it slightly more complex allowing the user to select the refresh interval.   This post contains…

1. A couple of Examples.
2. Reference materials
3. Step-by-Step.

Examples

**Warning** if vizzes below are not loading, check on the browser navigation bar for a “safety alert” and allow loading the “unsafe scripts” /* It’s just Tableau */

Embedded viz that refreshes every 5 seconds (check that clock!) designed by Russell Christopher

If the viz is chopped above, try opening it here (and load “unsafe scripts”).

Embedded viz that allows the user to modify the refresh time by interacting with the viz itself. Selecting a coloured square (Tableau mark!) will change the refresh time. There is, thus, a bi-directional communication: the web object loads the viz, interacting with the viz changes a variable in the webpage that drives the refreshing time.

If the viz is chopped above, try opening it here (and load “unsafe scripts”).

Reference material

1. Tableau: Nicely surprised by the quality and simplicity of the support material developed by Tableau. Very didactic and easy to follow — and I’m a completely Javascript layman. All of them: the manual, the interactive examples and, especially, the videos and examples  in GitHub & Youtube.
2. Russell Christopher: the first example (basic, refresh every 5 seconds) and the dashboard & idea of using a clock are entirely his.
3. Tamas Foldi plainly a genius with eye-opening material.
4. GitHub: I’ve saved here all the material I’ve used in this proyect.

Step-by-step

Self-refresh:

The idea is super simple: let’s create a minimal webpage with a single web object to load the viz using Tableau JS API. Then, let’s use Javascript in the webpage to reload the viz.

HTML

This is all the body of the page: a brief description followed by a “div” element (I called it “myViz”) that will start as empty. The ‘onload=”initialize();”‘ is the command to, when the page loads, launch a function called “initialize” that we’ll see below.

JAVASCRIPT

First thing we need is to call the API. Here, I’m using Tableau Public’s API.

<! – Importing Tableau API – >
<script type="text/javascript" src="https://public.tableau.com/javascripts/api/tableau-2.js"></script>

This now allows us to use its methods in our script. In the body of the webpage we call the “initialize” function, which is loading the viz in the proper element (“myViz”). To do so, we pass the url of the viz along with other parameters to configure the viz (size, with or without the toolbar, etc.)

Looking at the last line, we are creating a “new” tableau.Viz, this is a new Viz object that belongs to the “tableau” module (the API we initialize at the beginning). We are storing that object in the variable “viz” (which is not defined in this function but rahter defined in the main environment). The function “tableau.Viz” receives thre parameters:

1. The HTML element where we want to place the viz.
2. The url of the original viz.
3. A list of options.

Each of these parameters is initialized inside the “initialize” function and stored in the variables: placeholderDiv, url & options.

Basic Page:

If we combined the HTML section with the JS, add a bit of structure with a title, a script section (that will hold the Javascript), the definition of the “viz” variable and the “html” tags… we have a very basic (but functional) webpage that will contain the embedded viz when it’s loaded.

This is the starting point to get it to self-refresh.

Auto-load:

With the basic page already created, the additional steps to include the self-refresh are minimal. Just a couple of additional lines:

1. One to define the function that will launch the refresh of the viz. function refreshView(){ viz.refreshDataAsync(); }
2. Another to call this function with a determined periodicity. setInterval(refreshView,5000);

The function “refreshView” calls one method/property of the viz class: “refreshDataAsync()” which is equivalent to clicking the refresh button from the toolbar. The function setInterval() calls another function after a set number of milliseconds. The final version is here (don’t forget to load the “unsafe scripts”), and the code is in GitHub

Self-refresh with a twist: controlling the refreshing interval from the viz

Using as the starting point the previous viz and webpage, the aim is now to allow users to modify the frequence for the refreshing from elements in the viz. In essence, the webpage controls the frequence of refreshing, interacting with the viz modifies the value stored in the page, that now uses it as the new value to refresh the viz.

HTML, JAVASCRIPT and just a pinch of CSS

In addition to allowing the selection of the interval, I’ve included a counter to follow up the time left until the next update and how the values change after interacting with the viz. This is done in one line of HTML:

It’s an empty “div” of the class “circle”, void of content to begin with, but a little javascript will pass the value, in seconds, of the refresh interval.

Spiced with just a little bit of CSS:

The meaty part comes now in javascript, although it’s basically just a modification of the one used in the “basic page” above.

It’s very similar to the previous one. The “viz” variable is initialized, “refreshView” is defined, viz is initialized and an interval is set to launch the refresh function.

Main differences?

1. The interval value is now stored in a variable “ourInterval”, this will allow modifying it afterwards.
2. Inside the function that initializes the viz, we now call a new function “listenToMarksSelection” –which I will explain later– that, importantly, is called after “onFirstInteractive” that, according to Tableau is a: “Callback function that is invoked when the Viz object first becomes interactive. This is only called once, but it’s guaranteed to be called. If the Viz object is already interactive, it will be called immediately, but on a separate ‘thread.‘”
3. Lastly, not only the value of the interval, but the interval itself is stored in a variable “refreshInterval”, this will let us destroy it and recreate it again.

The second, juicier, part comes now: How can we pass the value from the selected mark in the viz to the variable “ourInterval” so that we can modify the refresh time? The code is as follows:

May look complex, but can be broken down into easier to digest bits:

1. The first bit, “listenToMarksSelection”, tells the browser to be on alert and, after selecting any mark in Tableau, call the second fucntion “onMarksSelection”.
2. This, in turn, captures all the selected values and launches the third bit: “reportSelectedMarks”.
3. In theory, one could select multiple marks, even though this example is design to get only one value. The bit about “reportSelectedMarks”…
   1. cycles through all the selected pairs of “measure & value” and, if the measure is called “Value”
   2. captures the value, multiplies it by 1000 (intervals in JS are in milliseconds),
   3. resets the time left counter to sync the clock
   4. destroys the previous interval
   5. and replacecs it with a new one with the new value.

The final outcome is here and you can find the code in github

Thanks for making it to the end, and do let me know your thoughts. Next time, we’ll be triggering alerts in the webpage based on data!