This article is by Ian Wi and originally appeared on the Alteryx Engine Works Blog here: https://community.alteryx.com/t5/Engine-Works-Blog/We-All-Start-Somewhere/ba-p/371822
Making Things Pretty
The role of the HTML GUI SDK is, to me at least, simple: it allows users to create a more customizable macro interface. Now, the idea may sound daunting, and the process does entail some coding, but, fear not, prior to attempting this challenge, I had no previous exposure to the land of JavaScript or HTML coding, so if that’s you, then I hope this will be a good resource to get you going.
The ‘Create Todoist Task’ Tool
In case you haven’t heard of Todoist, it is a task management tool that allows users to track progress of their projects. The purpose of the ‘Create Todoist Task’ tool is to make use of the ‘Todoist’ API to create a task on the user’s task list.
The reason this could be useful for Alteryx users, is, say, they want to automatically generate a task on their Todoist list in case a workflow fails to run as expected - something along the lines of Workflow X has failed, investigate by DATE.
Now, when you want to design a tool using the HTML GUI SDK then you first need a macro that you want to amend the interface of, so:
Step 1. Create macro with standard interface
In the case of the ‘Create Todoist Task’ the macro is relatively straight forward.
There are a series of interface tools which are designed to create the body of the post string which contains the task details, to which we then use a download tool to create the ‘POST’ request to the API.
I’ve made use of some of the additional parameter options such as the ability to define the due date of the task and set the task priority.
This results in an interface that looks something like the below…
Which although is fine and functional, visually it isn’t the most enthralling interface.
If you wish to see more detail regarding the use case for the tool, please check out this community article.
The File Structure
So, given I had absolutely no idea about the subject area, we started with some googling, and stumbled across a post on the Alteryx Community, which outlines the process. We found a few holes in this and I will try and point them out as we move through.
To build your nice interface you will need a minimum of 4 files:
- TOOLNAMEConfig.XML
- TOOLNAMEGui.html
- TOOLNAMEIcon.png
- TOOLNAMEEngine.yxmc (your macro)
The file 'TOOLNAMEConfig.XML' contains information about the macro, author names, descriptions, tags, etc. It also contains a tag to whether this macro has a 'Macro' engine, or another engine type (remember you can build tools using Python or C++ too).
It also contains key information regarding the inputs and outputs that you have in your macro.
The file 'TOOLNAMEGui.html' contains the detail of your widgets and how they link to the interface tools in your original macro. Building this file as a newbie, is likely where you may get a bit stuck!
'TOOLNAMEIcon.png' is your macro icon, and as mentioned previously, you of course need your macro which acts as your engine.
These files should lie in a file structure like shown in the screen shot, where the .yxmc sits within the 'Supporting Macros' folder.
In order for Alteryx to pick up a HTML GUI macro, you should place this folder structure in its own folder, ie: 'TOOLNAME', and then place this in the following location:
C:\Users\YOURUSERNAME\AppData\Roaming\Alteryx\Tools
If you've ever used a .yxi (Alteryx installer file), this is where your tools will get added automatically, hence why you see everything automatically in the right folders and embedded in the product.
Anyway, as you’re probably thinking, THIS MUST BE A BIT OF A PAIN TO DO.
Thankfully, it's not! Alteryx has created a tool generator which creates an appropriate folder structure in the correct location for you. The files will contain pretty much all the information you need to build your macro - the only thing you need to do is delete some code! BINGO!
This video shows the process which Peter and I went through to install the tool generator and then how we used it to generate the files outlined above:
Once these files are created, if you restart Alteryx, your macro will now appear in the toolbar. If you bring it onto the canvas you will see that your tool has the beginnings of a fancy HTML GUI interface, containing all the widgets that Alteryx makes available for you to use.
Bringing in Your Work
Now that your tool is available in the Designer product, you can bring the tool onto the canvas. Now if you then right click on the macro, you will see that the macro is simply a 'macro input' with the detail I provided, including the name and anchor label (of course if you defined multiple inputs and outputs they would all appear here).
Our first task is to take our already built macro and paste its contents in here. REMEMBER, IT'S ABSOLUTELY KEY TO CHANGE THE 'INPUT/OUTPUT NAME' AND ANCHOR ABBREVIATION WITH THOSE DETAILS SPECIFIED IN THE TOOL GENERATOR. If you want to change the abbreviation (because you can't leave the tool generator blank) then do this. However, your change must be reflected in the TOOLNAMEConfig.xml file as specified in the <Input Connections> and <Output Connections> tags.
Jazzing Up Your Interface
Once you have done the above step, you can now start configuring the GUI, which is done by editing the TOOLNAMEGui.html file. I suggest opening this in something like Brackets, Notepad++, or Atom.
The HTML file is split into two parts: the top part, which exists within the 'Article' element, contains the elements that exist within your GUI. By default, as you saw a couple of photos above, all the code exists for each of the widgets already.
The second part of the script is within the script tags. This is coded using JavaScript and contains information for those items which are not loaded with data. For example, you might see a drop down which requests a pre-made list of values, or a numeric spinner which has limits.
We'll dive into each part separately. Also, the CSS (styling) is defined at the start within the HTML, so you can make changes here too.
The HTML within the article tags looks like this:
Firstly, you have a section. A section is a styling element. In theory you can have all your widgets inside a single section or have them in separate sections which will give them more space.
Let’s take the toggle bar as an example, which can act like a drop down in a standard Alteryx interface, as the user can select just one value.
The above image also shows how each of the elements within the HTML is linked to the macro interface and the macro itself.
The red box, highlighting the H2 tags, is simply a title, it doesn't have to be there, but of course, it’s helpful for our users if it is.
The blue box, which highlights the type, we should leave as is. This is how Alteryx defines what widget you want, and this is actually referencing another file which sits in your Alteryx install to build out the relevant interface.
The final part, which is the key part, is highlighted by the green box. The widget ID should reference the name given in the annotation of your interface tool in the macro; this is how Alteryx makes the link and passes the values to the appropriate part of the macro. If you mess this up, then your macro will not run correctly!
Repeat this for all the elements that you want in your macro. This process should be quite simple, copying and pasting and cutting elements that exist in the placeholder script.
The order of the widgets in the script defines the order within your interface.
As mentioned before, the second part of the script allows us to create default values, and those values that should pre-populate in things such as drop downs or toggle bar lists.
Again, Alteryx gives you a baseline script to give you a head start.
First thing's first: delete any scripts that appear to relate to widgets that you haven't used. Below is where we perceive there to be a gap in the documentation post linked to at the start of the article.
Take the image above.
We made the reference from the string 'Numeric Spinner 2', which is what our widgetID was within the original HTML. We changed this to be 'DueDate' and we changed that here too.
What we weren't aware of is that 'ConstrainedNumber' is also supposed to be a reference to this widgetID.
This error in naming is within the script for all widgets. Basically, anything that looks like it is referencing a widget should be changed to your widgetID as you defined in the HTML and within the name of your interface tool on the annotations tab. This issue is highlighted in the above image through the green rectangles.
With those widgets that require a pre-populated list, you simply need to amend the placeholder list values and add yours (adding to the list further values if it's longer than three in length). Again, this is relatively straight forward, and you can see how they reflect in your GUI.
This is done in ‘name:value pairs’; i.e. the name is what the user sees (also known as the ‘label’) and the value is what is actually passed into the macro.
However, not all widgets need to be referenced in the JavaScript part of the code. If you have an element that is being loaded with data, i.e. your macro interface tool is connected to the metadata of your macro input (so you can populate the drop down with a list of fields for instance), then you do not need anything in the JavaScript section relating to this object. However, an additional attribute is required in the HTML script, this HTML element is known as 'data-item-props'.
Remember that the red box below is simply specifying a header in our interface. There are now two references to the name within the annotations tab of our interface tool, in both the data-ui-props for the 'widgetID' and within the data-item-props for the 'dataname'.
The second blue box, 'Field Selector' tells Alteryx that we want to select fields: simple. This won't change if you are using it for this method.
In theory, once you have done the tasks above for each of the elements, you are done and can hit save and start using the macro with its fancy HTML GUI.