The Prestige: Dynamic Macro Interfaces With the HTML GUI SDK

[NeilR]

On this blog we've featured a couple of articles explaining how to convert a macro's interface to HTML. Most recently, Using the HTML GUI SDK as a Coding NOOB, and earlier, Building an HTML Macro (where @Ozzie coined the term HTML Macro). If you're just getting started with the HTML GUI SDK, both articles are well worth your time - @Ozzie's article gives a little more background, and @BenMoss's fills in some of the gaps. Both articles teach you how to create awesome tools that are worth installing - a Create Todoist Task tool and an Email Parse tool. The scope of both articles is to take you through replicating the interface of the underlying macro with HTML, and stopping there:

For the scope of this article, we will only be mimicking the macro interface in our HTML front end. However, with the concepts presented in this article, you should have the basic tools and knowledge to make your HTML Macro have even greater levels of interactivity than a regular macro interface can provide.

- @Ozzie

You might be thinking wow this is a lot of effort just to make the standard macro/tool interface look a bit more aesthetically pleasing; but having a HTML GUI opens up lots of possibilities...

- @BenMoss

Let's get into one of these possibilities. The following article will show an example of how to use the HTML GUI SDK to build a dynamic interface that completely changes the functionality of a simple underlying macro.

---

The Macro (The Pledge)

We'll start with a simple macro. The Image tool is designed to work with images on your laptop. Do you know where there are a lot of other great images? On the web. Putting a Download tool in front of the Image tool adds this functionality, then adding a couple of Interface tools turns the workflow into a tool for pulling in images from the web, given a URL:

This now gives you a tool with an interface that looks like this:

Plug in a URL, and the image is now in your workflow, ready to embed in your report. This simple macro is attached at the bottom of the post.

The Dynamic Interface (The Turn)

If we reconstruct the interface with the HTML GUI, as explained in the blog posts mentioned at the beginning of this article, it would like this:

Arguably it looks a little nicer and more modern, but the tool's functionality remains the same. What if we could show a preview of the image in the configuration panel? Taking it a step further, what if we could search for an image rather than supply the URL? Enter Unsplash. This is the tool interface that we're going to end up with:

HTML GUI SDK (The Prestige)

Now let's see how to build that. The first thing we'll need is an HTML interface. Since all we need is a search box, a submit button, and the preview image, it's short and sweet:

<form onsubmit="changeImage(); return false">
   <input type="text" id="search" placeholder="Blank for Random Image">
   <input type="submit" value="Search Image">
</form>
<br>
<img id="preview" src="">

Now on to the JavaScript. You may have noticed in the HTML snippet above a reference to a changeImage function that will get called when the user clicks the Search Image button. Let's go ahead and create that function:

var xhr = new XMLHttpRequest()

changeImage = function () {
   var terms = document.getElementById('search').value
   xhr.open('GET', "https://source.unsplash.com/600x800/?" + terms)
   xhr.send()
}

This function grabs the user-supplied search terms from the text box and sends them to Unsplash. So far we haven't even touched the SDK.

Now, even though we will now no longer be requesting or displaying a URL from the user, we'll still want to store the URL that Unsplash returns to us so that the underlying macro can use it when the workflow is executed. So we'll need to add a data item, and we'll do this in the BeforeLoad method. Per the documentation, BeforeLoad is executed before the data stores are loaded, so is the right place to manually configure data items. The following code snippet is the first that actually touches the SDK.

Alteryx.Gui.BeforeLoad = function (manager, AlteryxDataItems) {
   var textBoxDataItem = new AlteryxDataItems.SimpleString('url')
   manager.addDataItem(textBoxDataItem)
}

A data item is how the HTML GUI SDK stores information to pass to the engine. Typically, they're tied to widgets - SDK-provided UI controls. In our case, we're foregoing using widgets because we don't want to display what's being stored (the URL). And remember, the name of the data item (url in this case) needs to match the name of the corresponding macro interface tool.

Now we need to grab the URL from the Unsplash response. What do we do with the URL? Two things:

1. Update the preview image.
2. Store the URL in the data item we just created.

var preview = document.getElementById('preview')

xhr.onreadystatechange = function () {
   if (this.readyState == 4 && this.status == 200) {
      preview.src=xhr.responseURL
      Alteryx.Gui.Manager.getDataItem("url").setValue(xhr.responseURL)
   }
}

There's only one thing left to do. At this point, we're only updating the preview when the Unsplash response comes back. There's another time we should update the preview: when the GUI loads. That way, if a user clicks off and then back onto the tool, the preview is still there. We'll do this in the AfterLoad method:

Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) {
   if (manager.getDataItem("url").getValue()) {
      preview.src=manager.getDataItem("url").getValue()
   } 
}

Now we have a tool where you can search for an image on Unsplash (or get a random image) for embedding in a report - and under the hood, it's still using the exact same seven tool macro that we started with - a macro that asks the user for a URL! Check it out in action below, and download it for yourself here.

---

Key Concepts

Let's review some HTML GUI SDK key concepts. Line numbers reference the final Gui.html file.

DataItems

A data item is the way the HTML GUI SDK stores the tool's configuration information and makes it available to the engine when the workflow is run. The data item name must match its corresponding interface tool's name. We create and name a data item on lines 55-56, set its value on line 44, and retrieve its value on lines 60 & 61.

Data item name must match interface tool name.

Widgets

A widget is an HTML GUI SDK UI control (like a drop down, numeric spinner, etc.) that binds to data items. We didn't use widgets here, because we didn't want to display the contents of the data item (URL). Instead we used pure HTML controls (the text box and submit button in lines 31-32).

Manager

The Manager provides methods to access and interact with widgets and data items. It is available globally: window.Alteryx.Gui.Manager. (source)

We used the manager on lines 44, 56, 60, and 61.

BeforeLoad and AfterLoad

Witness BeforeLoad starting on line 54 and AfterLoad starting on line 59. These are HTML GUI SDK methods that are automatically called at specific points in the lifecycle of a tool's configuration window, namely after you click on the tool but just before it loads (BeforeLoad), and after the data items have been loaded (AfterLoad).

webImage.yxmc