Note that it’s easiest to build this tool using a non-admin install of Alteryx. In an admin install, the HtmlPlugins directory defaults to read-only, but you’ll want to edit the files in the tool directory during the development process.
Each HTML tool lives in its own folder inside your Alteryx install, under bin/HtmlPlugins. In this case, we’re building a tool named JS_Eval, so it will live in a folder of the same name. The basic folder structure looks like this:
JS_EvalConfig.xml is the configuration file that tells Alteryx a tool lives in this directory. Its name has to be [Tool Name]Config.xml, and the folder has to be called [Tool Name]; these two names together tell Alteryx what to call the tool in the palette.
The XML config file should look like this:
The EngineSettings tag references the JS_EvalEngine.html file in this directory; that file can have any name or live in any subdirectory, as long as the name of the file is also set in this configuration file. The engine HTML file will do the work on your data when you run a workflow that passes data through your tool.
The GuiSettings tag references the JS_EvalGui.html and JS_EvalIcon.png files, which can also have any names, as long as they’re set in this configuration file. The HTML file will be used as the configuration panel for your tool when you click on it in a workflow. The icon is simply the tool’s icon on the canvas and palette.
For this tool, our GUI HTML file is quite simple. We’ll include two text boxes from the Alteryx library of configuration controls. The controls in this library are called plugin widgets; they’re modeled after standard HTML5 input controls, but have additional backend functionality that allows them to save any data entered into them as part of the Alteryx workflow file.
The GUI HTML file is a standard HTML5 file, with the same structure as a normal web page.
Finally, we implement the two SDK functions described earlier. The AfterLoad and Annotation functions are provided as part of the SDK, so will automatically be called by the Alteryx base library included at the top of the document. A full list of SDK-provided functions is available in bin/RuntimeData/HtmlAssets/Shared/1/lib/alteryx/gui/main.jsx. AfterLoad is run after the configuration is loaded into the tool: when you click on the tool in the workflow, Alteryx loads your previously-set configuration values from its XML into this HTML document, so that you can manipulate them in the configuration panel. AfterLoad is called after that load step is completed. In this case, it looks in the manager (which is a container for all of the data items being configured in this tool) for the NewField data item – which matches with the dataName of the first text box widget we added to the page. If the value of this text box is blank, the AfterLoad function gives that field a default value.
Annotation is another provided function which creates the canvas annotation – it simply returns the text that will be displayed underneath the tool on the canvas. In this case, it gets JsExpression – the dataName of the second text box – from the manager and returns it.
TheNewFieldName – a global variable – is simply set to the NewField value that was passed in as part of the config argument to PI_Init. (Note, again, that this is the same dataName that was set for the first plugin widget in the configuration GUI.)
The next function that will be called is II_Init. It’s called once for each incoming data stream; in this case, the tool has only one input, so II_Init will be called only once. While PI_Init was called without sending any response back to the engine, II_Init is expected to respond with the metadata for each of the fields it will be outputting – types, names and sizes. For this tool, we’ll be outputting the same fields that were given to us as input, plus one new field with the name that the user configured in the first text box – which we earlier saved as TheNewFieldName.
As this function is a little longer, I’ve documented it with inline comments that describe each separate task performed in II_Init. Once II_Init is done, we’ve told the engine what our tool’s output is going to be; all that’s left is to produce the actual output, which is the responsibility of II_PushRecords. Of the three engine functions we’ve implemented in this tool, II_PushRecords is the largest and most complex – I’ll document it with inline comments, as well.
We’ve now completed the final piece of our tool’s engine – we’re ready to start up Alteryx, pull this tool into a workflow, and run it against a live data stream. This example will pull stock quotes as JSON objects from a public REST API. The tool and sample can be downloaded here, or go to the GitHub repository if that’s how you roll.