Looking for Starter Kits? Head to the Community Gallery! Now formatted as YXIs for easy installation.

Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
8 - Asteroid

4ffdaf0d245ff2ea4a089507d3b99c1eLast week I introduced potentially new visualizations for Alteryx based on HTML5 and its associated parts like JavaScript and SVG. I started with a macro to write JSON data files from Alteryx. This week I continue the prototype with a macro to actually render HTML 5 into an Alteryx report.


Skipping to the end of the story, on the left is a chart created using nvd3 in Alteryx. I found some nice sample data for visualizing from the world bank showing the GDP of every country (and region) in the world since 1960. The selected data I chose to show is the top 10 countries by GDP since 1980 – the data before then seems to be lacking in some detail. I show the data as a stacked bar chart, which means that the top line is the total GDP for all 10 countries with each country’s part of the total shown by the height of a specific color.



imageIn screen capture of the module (on the right,) you can see the HTML5 tool (which is just a macro for now). Mostly what you see is how simple the module is, but there are still some nice details. The Select tool is selecting which countries I want to show and the Filter tool is picking a subset of the years.


I point this out just to show that even though this is a macro and a prototype, it is immediately usable in a release version of Alteryx and the charts will respect the data selections that are being fed in to it.


At this point, if you are not interested in the details, you can go ahead and download the module here. Inside the module you will see a rendering of the same data as a line chart in addition to a stacked area chart, and you will also see how easy this would be to re-use.


Technical Details

The first problem to solve of course is the actual rendering of HTML5. Remembering that this is only a prototype and I want something that can plug into the current Alteryx 8.6 release, that means I need to use a Run Command tool. Fortunately there is an absolutely perfect open source project that does exactly what I need: PhantomJS. This is a single file executable that (among many other features) can render any web page to a PNG. It is based on a slightly out of date version of WebKit, but it is modern enough for a prototype. Presuming something like this makes it as a future feature in Alteryx, this choice will clearly need to be revisited, but for now all is good.



imageimageIn order to give the appearance of seamless integration, I needed to make a macro that integrates HTML 5 into Alteryx. You can see from the screen capture that it is a cross between the R tool and any random reporting tool. Like the R tool you can put code directly into the configuration. In addition to the code, you get to specify the size of the canvas in inches and the resolution of the output, like other reporting tools. This allows you to print reports containing these charts and not have them look pixellated. When displaying on-screen, it is best to keep the resolution at 1X, otherwise the scaling down can make it look fuzzy.




The next thing in the screenshot that you will see is my “hello world” html code. This is an exact copy and paste from a simple introduction to SVG in HTML 5. You’ll also notice that I borrowed the icon from w3.org – it was good of them to make a standard icon for HTML5 that can be re-used.


In short, here is a tool that you can put in any HTML5 code and get a report snippet out. I think that’s pretty cool!



The next step was to figure out something more interesting to show. I started with nvd3, only because it was one of the more common libraries online, but there is no specific ties to it from this tool. Any of the open source libraries would work equally well. I had a little trouble with the bind function, since the browser in PhantomJS is just old enough to not support it natively. Fortunately the Mozilla documentation came to the rescue with a way to implement it in JS for old browsers, so I had to include their code prior to including nvd3.


Once I had nvd3 running, I just needed to figure out how to translate the JSON data coming from Alteryx to the format that nvd3 expects. I wanted to do it in as generic a way as possible so that it would accept any data that Alteryx sends. The macro sends in the JSON data (as Column Arrays) to a function called alteryxData(). In the end, it as a fairly simple JavaScript function to translate the raw JSON object to the form that nvd3 expects, but it took me a while because of the lack of documentation.

 function theData() {
  var ret = [];
  var data = alteryxData();
  var names = data["Name"];
  for (var name in data) {
    if (name != "Name") {
      var v = data[name];
      var out = [];
      for (var i = 0; i < names.length; ++i) {
        out.push({ x: names[i], y: v[i] });
      ret.push({ values: out, key: name });
  return ret;




Controlling the order of execution

Alteryx is data driven, not code driven, which can make it difficult to control the order of execution of tools in a module. For the programmers, Alteryx is basically a functional_programming environment, not procedural. Usually it doesn’t matter, because the connections themselves force a specific order of processing. In this case it matters though, because I am using a Run Command tool that in effect has 2 inputs: 1 for the JSON data and 1 for the script itself.


In this case I needed to make sure that they both get written before the Run Command tool is executed. I used a little trick here by joining the 2 streams together and then pulling them back apart. You can see that I add a rarely used BlockUntilDone tool after the Join. One of the (documented) side effects of it is that it outputs one stream and then the other. It will always do it in the same order, so once you get the 2 streams running in the order you need, you can count on them always running in that order. This way I can guarantee that both the script and the JSON data will be written before PhantonJS executes.


JavaScript Include Files

You can see from the sample I made, that this tool supports including external scripts:

<script src="./d3.v3.js"></script>


I had to do a little trickery to support this. I wanted to keep all temporary files in the %temp% directory so they get cleaned up by Alteryx, so the script will not actually be written to the directory that the module is running from. What I did is explicitly search for ./ and replace it with the proper %temp% directory. This means that you can include JS & CSS files as long as they are in the same directory as your module and also as long as you preface them with ./ . Also, of course you can use absolute paths or URLs.


Next Steps

Next Wednesday I will continue exploring some of the various things that can be done with HTML5 in Alteryx. I expect the next post in the series to be a lot less technical and much more of a show & tell.


Once again - you can go ahead and download the module here.


Thanks for reading,




This post originally appeared at http://inspiringingenuity.net/2013/10/16/alteryx-html5-visualizations/