You are here:

Using only SetConfiguration and GetConfiguration

The main reason one would use SetConfiguration and GetConfiguration alone, and none of the higher level abstractions such as data items or widgets, is because they already have their entire tools UI all setup and put together. SetConfiguration and GetConfiguration give a really simple way to take an already complete UI, and fill in its form fields from the tools XML, as well as save the tools XML given the already developed UI.

To use this approach, the tool developer must create these two functions: window.Alteryx.Gui.SetConfiguration and window.Alteryx.Gui.GetConfiguration.

SetConfiguration

This function will be given the current tools XML configuration as the first and only parameter. It’s executed when you click on the tool. Specifically, it executes first thing when the tool configuration pane loading your tool’s configuration UI page has signaled it is no longer loading the HTML page. The object handed to this function is in fact a JavaScript object with the current tool configuration as well as other relevant information for the tool developer, including upstream fields available to the tool, the tool ID, and whether or not it is presently in a macro. The full structure of this object is detailed in the full SDK API reference documentation. The tool’s configuration is in a property named Configuration which is an object constructed by using NewtonSoft Json.Net’s JsonConvert.SerializeObject function on the System.Xml.XmlElement object containing the current tools configuration. For details on how this will turn your tool XML configuration into JSON, you may reference the source here. The JSON.Net documentation is here.

Once the reading of the tool’s configuration into the page’s UI controls is complete, at the end of the SetConfiguration function, there must be a call to notify Alteryx that the configuration has finished loading correctly. This call will be done by executing the window.Alteryx.JsEvent function with a JSON stringified object { Event: ‘SetConfiguration’ }


window.Alteryx.JsEvent(JSON.stringify({Event: 'SetConfiguration'}))

GetConfiguration

The purpose of this function is for Alteryx to get your tool’s configuration from the UI to store in the workflow. This function will be executed as the last thing the browser in the tool configuration pane does before closing. Any time you change tools, or click out of the tool pane in general (for instance, to run the workflow), this will be executed. The way it passes the configuration object to Alteryx is by executing the window.Alteryx.JsEvent function, with a stringified object of the given structure:


window.Alteryx.JsEvent(JSON.stringify({
  Event: 'GetConfiguration',
  Configuration: {
    Configuration: /\* your tools configuration object here \*/
  }
}))

By giving this parameter to the window.Alteryx.JsEvent function, Alteryx will again use JSON.Net to convert the JSON object in the Configuration.Configuration property described above into the XML which will be persisted in the workflow.

Using only SetConfiguration and GetConfiguration example


<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Location tool</title>
</head>
<body>
  <h1>Location:</h1>
  <br />
  <label>X:</label><input type="text" id="locationXValue" />
  <br /> 
  <label>Y:</label><input type="text" id="locationYValue" />
  <script type="text/javascript">

     window.Alteryx.Gui = {
       SetConfiguration: function (currentToolConfiguration) {	
         // Grab the values from the incoming tool configuration, and set the UI
         var xVal = currentToolConfiguration.Configuration.Configuration.X
         var yVal = currentToolConfiguration.Configuration.Configuration.Y
         document.getElementById('locationXValue').value = xVal
         document.getElementById('locationYValue').value = yVal

         // Notify the Alteryx Designer you are done handling SetConfiguration
         // If you don’t do this, the GetConfiguration will not be called
         window.Alteryx.JsEvent(JSON.stringify({Event: 'SetConfiguration'}))	
       },
       GetConfiguration: function () {
         var xVal = document.getElementById('locationXValue').value
         var yVal = document.getElementById('locationYValue').value
         // The Alteryx Designer has requested the tools configuration
         // Provide the configuration to the Alteryx Designer with
         // a call back through JsEvent like this:
         window.Alteryx.JsEvent(JSON.stringify({
           Event: 'GetConfiguration',
           Configuration: {
             Configuration: {
               X: xVal,
               Y: yVal
             },
             Annotation: 'X:' + xVal + '\nY:' + yVal
           }
         }))
       }
     }

  </script>
</body>
</html>