How To - Tableau Javascript API for Dummies. Vol 1: when the API is not needed.

Let me preface this by explaining that I have zero prior experience with Javascript. So when I say “for dummies” I actually mean “for people like me with no JS knowledge” (actually, for people like Eliott and me, as we tackled this project together during “Back To School” week).

Thisis the first of a series of posts to make people more familiar with (and lessafraid of) Tableau’s API. Only the basics.

First question I had about the API was… What does it do? And the second was… When is it needed?

What does the API do? It allows the integration/embedding of vizzes in web pages or web objects; the interaction with the original viz; and the communication between the viz and the environment it’s embedded into (as in transferring information from the webpage to the viz and viceversa).

In this post I focus on some use cases where the API is NOT needed. For instance, when you are trying to embed the visualization in WordPress (or in any web for that matter).

When is the API not needed?

Anytime there is no need for combining information between the web page and the viz. i.e. if the interaction with the viz is not going to modify the web page and the interaction with the webpage is not going to modify the viz.

What would you use in those instances then?

If the viz does not need to be embedded in a web object, the regular consumption is directly through Tableau Server.

If the viz needs to be embedded in a web object, there are two main methods:

1. Iframe.
2. Web embed code.
3. A barebones template can be found here (open and save it to modify the html).

What are they / how to use them?

iframe

An iframe is, to keep things simple, a web page insde another web page. It can be done with pure HTML:

<iframesrc='https://www.example.com/'name='SubHtml'width='400'height='500'frameborder='1' scrolling='auto'>Alternative text for browsers that do not accept iframes.</iframe>

Many applications (i.e. WordPress) will have a plugin to converet url in iframes. Once the plugin is installed, just follow their directions. Each plugin will vary slightly, but most likely will be a variation around this theme:

<br>[</br>iframe src='https://www.example.com/' name='SubHtml' width='400' height='500' frameborder='1' scrolling='auto']Alternative text for browsers that do not accept iframes.[/iframe]

Either way (either using pure HTML or using plugins) the necessary URL can be obtained from Tableau Public (or your own Tableau Server):

embed

Using the native code (HTML + Javascript)  directly provided by Tableau (Public/Server)

HTML:

<div id='viz1549747309453' class='tableauPlaceholder' style='position: relative;'><noscript><a href='https://dsmdaviz.com/2019/01/marginal-tax-rate-simulator/'><img alt=' ' src='https://public.tableau.com/static/images/Ma/MarginalTaxRateSimulator/MarginalRate/1_rss.png' style='border: none' /></a></noscript><object class='tableauViz' style='display: none;' width='300' height='150'><param name='host_url' value='https%3A%2F%2Fpublic.tableau.com%2F' /><param name='embed_code_version' value='3' /><param name='path' value='views/MarginalTaxRateSimulator/MarginalRate?:embed=y&:display_count=y' /><param name='toolbar' value='yes' /><param name='static_image' value='https://public.tableau.com/static/images/Ma/MarginalTaxRateSimulator/MarginalRate/1.png' /><param name='animate_transition' value='yes' /><param name='display_static_image' value='yes' /><param name='display_spinner' value='yes' /><param name='display_overlay' value='yes' /><param name='display_count' value='yes' /></object></div>

Javascript:

<script type='text/javascript'>var divElement = document.getElementById('viz1549747309453');var vizElement = divElement.getElementsByTagName('object')[0];if ( divElement.offsetWidth > 800 ) { vizElement.style.width='375px';vizElement.style.height='694px';}elseif ( divElement.offsetWidth > 500 ) { vizElement.style.width='375px';vizElement.style.height='694px';}else { vizElement.style.width='100%';vizElement.style.height='694px';}var scriptElement = document.createElement('script');scriptElement.src = 'https://public.tableau.com/javascripts/api/viz_v1.js';vizElement.parentNode.insertBefore(scriptElement, vizElement);</script>

It may look complicated but, in reality, one just needs to copy the code generated by Tableau:

Didn't I say you didn't need an API and I just used one? Well, technically... yes. However, this is a 'different' API from the one we will use to interact with and manipulate the viz.

An example: embedding a viz in WordPress step by step

I'm going to continue using as an example the viz from above ( my “Marginal Tax Rates” calculator) available in Tableau Public. Deciding in favor of iframe and native code, of iframe using a plugin or the Tableau-generated web-embedding code might be a question of preferences, convenience or requirements. It may be the case, for instance, that the admin disallows the use of <iframe> tags, but may have made an alternative plugin available.

iframe

with native code

1. Start a new post/page in WordPress.
2. Get the url of the viz from Tableau Public.
3. Modify the code to embed the viz as an iframe with this URL.

<iframe src='https://public.tableau.com/shared/MJ7BTTN3K?:display_count=yes' name='SubHtml' width='400' height='700' frameborder='1' scrolling='auto'>Marginal Tax Rate Simulator --or why you'll remain unaffected by the 70% tax rate proposed by @AOC.</iframe>

4. Copy this code in a web object in the blog (or use the “edit as HTML” option in a block text/paragraph in the new editor).
5. Modify the parameters to adjust to your viz.

with some plugin

1. Verify that there is some plugin to handle iframes already installed (else, install it first).
2. Start a new post/page in WordPress.
3. Get the url of the viz from Tableau Public.
4. Follow the directions for the plugin (usually, some form of wrapping the url with iframe in square brackets).

5. Modify the parameters to adapt to your viz.

embed

Using native code (HTML + Javascript)  provided directly by Tableau (Public/Server)

1. Start a new post/page in WordPress.
2. Get the url of the viz from Tableau Public.
3. Copy the code in an HTML object.
4. Modify the parameters to adapt to your viz.

Thanks for making it to the end. In the next volume, I'll start exploring a couple of actual use cases for the API (autorefresh and exchanging info with the webpage).

A barebones HTML template to play with embedding/iframe can be found here. Save it locally and edit with a text editor to explore with different url and parameters.