Integrating D3 with Tableau

Tableau is powerful visualization tool used in Business Intelligence Industry. It offers a lot of visualizations which can be used to transform raw data to a visual format which is much easier to understand. But sometimes the built-in visualizations are not enough when we have some special type of data which require a specific visualization. In that case, tableau has a feature of extensions. Using the extensions API we can create any visualization by utilizing the power of Javascript.

So we are going to create a sunburst chart using D3 and integrate it with tableau using the Extensions API. You can create other visualizations as well using the same method.

The tableau extensions API basically gives you access to the Tableau Dashboard and its underlying data inside a web page using which you can create whatever you want, be it a fancy D3 chart or a data table with some special features.

For this, you need some basic knowledge of web technologies like HTML, CSS and JavaScript.

1. Create a dashboard in Tableau

First of all, we need to create a dashboard in tableau, for which we require a dataset. For the purpose of demonstrating heirarchical data I am using the following dataset : https://catalog.data.gov/dataset/unspsc-codes

Import the CSV file as new data source inside tableau and create two worksheets as follows :

Worksheet 1

The first worksheet shows the data as a table in a heirarchical form. It also contains a “Segment Name” filter which applies accross all worksheets. Make sure to create the sheet exacty like shown in the screenshot as the data we get from the worksheet inside the Extension depends on the way it is arranged inside the worksheet. The above format gives us the data in a heirarchcal format which is required to create a Sunburst chart.

Worksheet 2

The second worksheet contains a simple table to show individual rows. This would be used to filter out the rows based on the filters applied from the Sunburst chart.

Now create a new dashboard and add the first sheet to it and then the second one. The order in which we add the worksheets to the dashboard is important as we are going to fetch the data from these sheets inside the extension in the same order.

2. Create the Extension

Now, let’s create the extension which we will later add to the tableau dashboard.

A Tableau extension consists of a manifest file (.trex), a web page that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic.

Lets create a new folder and create a file named Sunburst.trex inside it. Paste the following content inside the trex file.

Sunburst.trex

The manifest file (EXTENSION-NAME.trex) is an XML file that describes the extension and provides information to register the extension with Tableau.

The url in the above file is the path to the webpage where the extension is hosted. Here we are going to host it on the localhost and port 8000.

Now create a folder inside it named lib and put the Extensions API JavaScript library (tableau.extensions.1.latest.js) in it, which is available inside lib folder in the Extensions API sample provided by tableau here. You can also find this file in my repository mentioned at the end of this post.

Create a new file named index.html inside previous folder which looks like following :

index.html

This file is the entry point of the extension. It includes the Extensions API javascript library, D3, and lodash which we need to create the custom visualization. It also contains some basic styles for our extension.

Next, create the script.js file which contains all the logic of our extension. It fetches data from the dashboard, converts it into appropriate json format and then plots the sunburst chart using d3. It also adds the event listeners for filters both to and from the extension.

script.js

WHOA! That’s a lot of code! Let’s try to understand what’s actually going on here. First of all we are executing a function when the document is ready, which ensures that all our dependencies are loaded. Then, we have declared some variables which we will need later.

Next, tableau.extensions.initializeAsync() is the function provided by tableau extensions API which initializes the extension. It returns a promise so we attached .then() to it which is also a function and accepts another function as an argument, that we want to run when the promise is resolved successfully.

tableau.extensions.dashboardContent.dashboard is the object which gives access to different parts of the dashboard. We have fetched the worksheets included in the dashboard using tableau.extensions.dashboardContent.dashboard.worksheets which gives us an array of worksheets, so we have assigned both of our worksheets to the variables respectively.

Inside the getDataAndPlotChart function we are using getSummaryDataAsync function provided by the extension API to get the underlying data of a worksheet. After which, we have formatted the data to get an array of objects (group of key-value pairs), where each object represents a single row like below:

{
"Segment Name" : "Defense and Law Enforcement and Security and Safety Equipment and Supplies",
"Family Name" : "Conventional war weapons",
"Class Name" : "Naval weapons",
"SUM(Number of Records)" : 1,
}

Then, we have converted the data into hierarchical JSON required for plotting sunburst chart by d3, using groupBy function of lodash. After which we have called the plotChart function which contains the d3 code to plot the sunburst chart and also adds various filters to worksheet2 on click of each section depending upon the depth of section in sunburst.

In line no. 60, we have added an EventListener to the worksheet1, which listens for filterChange events and executes our filterChangedHandler function whenever a filter is changed in the worksheet1. The filterChangedHandler function checks if the filter applied is on “Segment Name” and refreshes the data and the d3 chart if so.

3. Host the Extension

Now, we have to start a web server to host the extension. For this, you can either use python simplehttpserver if you have python installed by running the following command in a terminal inside the folder which contains the html file :

python -m SimpleHTTPServer 8000

Or you can use the http-server npm package for which you have to have node installed. For this, run the following commands in a terminal inside the same folder :

npm install http-server -g 
http-server -p 8000

Note that the port here is the same that we had entered in the url inside the trex file.

4. Add the extension to the Dashboard

To add the extension to the dashboard, click and drag Extension from Objects pane (at the lower left corner) into the dashboard. Select “My extensions” from the dialogue box which opens.

Browse and select the trex file that we just created. Select “OK” from the next dialogue box and wait for a few seconds.

Voila! We have Successfully created our own Tableau Extension!

If you don’t see the Sunburst chart after a few seconds, you can debug the issue by following this guide :

Debug Extensions in Tableau Desktop

You can find all the code in the following git repo -

WebDevRaj/tableau_sunburst

References:

Extensions API Home

D3.js - Data-Driven Documents