Blog Archive

Archived Blogs
NeilR
Alteryx Alumni (Retired)

Editor's note: this article has been archived because the experimental JavaScript Engine SDK has been deprecated.

 

In part I of the series I posted about the JavaScript tool, how to install it, and how to use it. This post describes how I created the tool's interface using the HTML GUI SDK.

 

The purpose of the interface of an Alteryx tool is to collect information from the user about how the tool should be configured, and pass that information to the engine so that when the workflow is executed, the engine knows how to process data for that tool. The configuration information is passed as XML. In fact you can see that XML by enabling Display XML in Properties Window under Options > User Settings > Edit User Settings > Advanced. Once that is enabled, you'll see a new XML tag icon below the wrench icon along the left side of the configuration window:

 

xml1.png

 

Click this icon and you'll see the XML that will get passed to the engine for a particular tool's configuration. Here we can see that this Summarize tool is configured to produce the sum of the Field1 column:

 

xml2.PNG

 

The HTML GUI SDK allows you to create a custom webpage to serve as a tool's interface and supplies the apparatus to create this XML based on user interaction with the webpage. If Alteryx Designer is a "glorified XML editor"(@Ned) then the HTML GUI SDK is an XML generator. It allows you to take advantage web technologies to create truly interactive interfaces on top macros (like the Google Sheets tools), C++ -based tools (like the Formula tool), and Python -based tools (coming soon!). The remainder of this post is not meant to provide comprehensive documentation for the SDK (which is coming soon), but rather give a taste of what's possible as demonstrated in the JavaScript tool.

 

The JavaScript tool's interface consists of three main items:

 

js1.PNG

 

  1. A text box for entering script files to import
  2. A button for inserting code snippets
  3. A code editor for typing code, with built-in syntax highlighting

I've implemented these using three pillars of web technology:

 

1. HTML

As previously mentioned, the HTML GUI SDK provides mechanisms to generate the tool's XML configuration to be passed to the engine. One such mechanism is "widgets" or controls (such as text boxes, drop-downs, etc) that will automatically generate the XML based on how the widget is configured by the user. The Script files to include text box is based on a Text Area widget. Notice the widget is implemented to look like an html element and sits in open html code, and the syntax looks similar to the standard HTML text area element (caution: I’m using v1; the syntax for the widgets will be somewhat different in the soon to be released v2 of the HTML GUI SDK, but this version of the syntax will still work):

 

 

<label for="includesId">Script files to include (comma separated URLs)</label>

<alteryx-pluginwidget type="TextArea" rows="2" dataName="includes" id="includesId"></alteryx-pluginwidget>

 

Thus when a user includes jquery like so: 

 

js2.PNG

 

The following XML is automatically created:

 

js3.PNG

 

2. CSS

The Insert Code  button is not meant to be a configurable item of the interface that will get written to XML, but rather an interactive helper to populate the code editor below it. Therefore we don't want to use a widget, and we're free to write our own code. In this case I borrowed some code from W3Schools.

 

Spoiler
/* Dropdown button courtesy of https://www.w3schools.com/css/css_dropdowns.asp */

/* Style The Dropdown Button */
.dropbtn {
background-color: #1691C6;
color: white;
padding: 10px;
font-size: 12px;
border: none;
cursor: pointer;
margin: 10px 5px 5px 1px;
}

/* The container <div> - needed to position the dropdown content */
.dropdown {
position: relative;
display: inline-block;
}

/* Dropdown Content (Hidden by Default) */
.dropdown-content {
display: none;
position: absolute;
background-color: #f9f9f9;
min-width: 150px;
box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
z-index: 100;
}

/* Links inside the dropdown */
.dropdown-content div {
color: black;
padding: 12px 16px;
text-decoration: none;
display: block;
cursor: pointer;
}

/* Change color of dropdown links on hover */
.dropdown-content div:hover {
background-color: #f1f1f1
}

/* Show the dropdown menu on hover */
.dropdown:hover .dropdown-content {
display: block;
}

/* Change the background color of the dropdown button when the dropdown content is shown */
.dropdown:hover .dropbtn {
background-color: #1380AF;
}

3. JavaScript

The code editor and all its syntax highlighting glory is courtesy of CodeMirror. CodeMirror is great. We use it for our Formula and Optimization tools. I was able to get the code editor working in about a dozen lines of JavaScript code.

 

Here's the key line of code that updates the tool's XML configuration every time the user types in the code editor:

codeEditor.on("change", function(codeEditor, change) {
   Alteryx.Gui.manager.GetDataItem('code').setValue(codeEditor.getValue());
});

This is made possible because earlier on we created a second Text Area widget, but hid it:

<div style="display: none">
   <alteryx-pluginwidget type="TextArea" rows="5" dataName="code"></alteryx-pluginwidget>
</div>

This code editor is a great example of all the amazing stuff that is out there in the JavaScript community - often open source and free to use - and how leveraging this community makes the HTML GUI SDK all the more powerful.