Easy as Pie React + D3 Chord Diagrams in Tableau
/A functional example of Tableau integration with Nivo (React + D3)
First things first...
Chris Toomey has done great work already in this space and I referenced his code and also asked him for help and input along the way. This write up builds upon his work and provides another integration technique and some additional capabilities within Tableau. Thanks for the guidance along the way Chris!
I am also leveraging code from Tamas Foldi and I’s earlier work on d3.js integration with Tableau, those posts are found here and here. He also helped me out with some of the interactive features in this example, so big thanks to Tamas for his help as well.
Second, the details...
Chris’ above referenced write up has a good intro of React for our purposes, definitely give his blog a read to get more information on that front. We are going to be integrating with and leveraging Nivo, which is self described by Raphaël Benitte (it's creator) as “supercharged React components to easily build dataviz apps, it's built on top of d3.” Nivo is one of many react component libraries that work on top of D3, each are different and bring their own features and focus to their projects. Here are a few more worth checking out (in no particular order):
I am going to assume you know how to leverage create-react-app and npm install to get up and running locally and import all the component libraries you will need. If you have not gone through this install process yet Chris’ blog walks you through some key steps you will need to complete, and Google is of course your best friend here. Here are the commands to run:
Create-react-app nivo_int
Cd nivo_int
Npm install tableau-api
Npm install nivo
That is it, if you run npm start at this point, your project will be bundled and rendered locally on your machine... Magic!
Once you have your local instance running, you should take a detailed look at how you want to structure your project and it’s components. This is really one of the key steps in the process and I would liken it to determining how you plan to layout your dashboard. For this effort we are going to create two components one to hold the tableau viz object and the other to house the embedded chord diagram within the Tableau dashboard itself.
Let’s do the easy stuff first and work on getting our viz to render on our page. Note: as Chris points out there is a npm package out there (tableau-react) that can make this very simple, but also is missing some of the api functionality. As such, I deferred to using Chris Toomey’s npm package tableau-api.
With using create-react-app we are going to modify the src/app.js to write our code for getting our viz on the page. This can be done by importing our tableau-api library and then leveraging it as we would in plain old html/js. Here is how that looks...
So now we run npm start again (or if you left it running it will hot refresh thanks to webpack) and we should have our viz rendered on our page...
Now we have our viz, but it isn’t doing anything special ... yet. Next we are going to work on the component which we will be embedding within Tableau and integrating/leveraging the Nivo library. The bare minimum we can do here is pull the data out of Tableau (via JS API) and send it to Nivo in order to build our chart (on the fly). We are going to try to take a few steps beyond that for this example, including, exposing in Tableau, all of the props available from Nivo. This will allow us to customize the chord to our liking from directly within Tableau! No additional code required (see section 3 below on how to implement this yourself).
Here are some of the key parts coded to allow for us to get these separate pieces to talk to each other.
In these two code snippets we see different aspects of how to get the two technologies to work together in order to accomplish our goal. Also, do not worry about re-writing any of the above code, you can easily access it on my git here. Click on the image below to view the interactive version on my GitHub.
This is a screen shot of the interactive example, click the image to visit the working version. Note: interactive version is working best on Chrome, but also functional in most current browsers.
Third, how to use this without writing code...
Here is a list of steps that you can take to use this without having to write any additional code.
Grab my git repo
Change the viz url in src/app.js
In Tableau:
Add a webpage object to your dashboard
If you are copying this to your own git repo then your URL will be https://<username>.github.io/<repo>
Pass desired parameters via CHORD PARMS parameter in Tableau. Note this is optional and you can see an example of the format required in my example Tableau Public workbook. This must be well structured JSON and I have not built in any error checking into this process yet either.
Enjoy your new d3 chord with zero additional code needed!
One other important item to note is that I have created four props that you can pass to make use of this technique. They are as follows (case sensitive and all values are strings):
dataSheet - the name of the sheet in Tableau you want to use as the data source (must be on the dashboard that you have webpage object on as well). I would also try to keep your sheet names pretty simple (e.g., avoid special characters, etc.). Default is first sheet found on dashboard.
inField - 1 of 2 dimensions you will be using for the chord flow. Default is first field found on sheet.
outField - 2 of 2 dimensions you will be using for the chord flow Default is second field found on sheet.
valField - the measure that you will be representing in the chord diagram. Default is third field found on sheet.
In addition to these four new props, you have direct access to all of the Nivo Chord Props via the process as well.
Fourth, what next?
Here are some next steps that we can take forward on this in my opinion...
Complete a few more features into this example, like, enabling two-way interactivity between Tableau and React+D3 (only one-way is enabled at the time of this post).
Adapt JS API code to Tableau's new Extensions API structure
This same method could be used to render any of Nivo’s available chart types or other React + D3 packages for that matter. Additional, functional examples would help demonstrate this and would not take all that much time to put together.
Updated on 12/4/2017
Additional example of Nivo integration, demonstrating the Stream component of Nivo working with Tableau.
Example integration of Tableau with Nivo Stream component. THIS IS A SCREEN SHOT OF THE INTERACTIVE EXAMPLE, CLICK THE IMAGE TO VISIT THE WORKING VERSION.
