Using lifecycle methods with data items

To pull in theJavaScript UI library with these pieces, the tool developer will need the following script snippet in their page’s head:

<script type="text/javascript">
    document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">')
  </script>

This snippet uses document.write because a user’s Alteryx installation may be anywhere on their machine, and this technique lets the window.Alteryx.LibDir specify where to find the UI library, regardless of where the user installed Alteryx.

Using the BeforeLoad method with data items is a versatile but rather clean and easy approach to creating a tool configuration UI. To use this approach, you have to pull in our JavaScript UI library. With this approach, you may use any UI control library you please, however by using the data items with our manager, the reading of configuration in GetConfiguration will be handled for you, as well as the persistence in SetConfiguration.

To implement the Alteryx.Gui.BeforeLoad function the user will use the following signature:

  window.Alteryx.Gui.BeforeLoad = function (manager, AlteryxDataItems, json) { /\*...\*/ }

The parameters are:

manager - this is an object which has implemented the SetConfiguration and GetConfiguration functions for you, this way you can use data items and it will handle filling them with data from the tools configuration for you, as well as persisting them in your workflow. It provides more facilities, such as calling a window.Alteryx.Gui.Annotation function for you to provide a workflow canvas annotation for your tool by simply returning a string. It also is used for interacting with the HTML GUI SDK widgets if you are using them, as well as providing an easy API for accessing upstream field and tool information. The manager’s full API is detailed in the full SDK API reference documentation.

AlteryxDataItems - this is an object which has the various data item type constructors on it, so you may new them up from it. The full listing of available data items you will find on this is listed below. Example:

new AlteryxDataItems.SimpleInt('X')

json - this is the actual JSON object handed to GetConfiguration which provides the tool’s current configuration data. The full description of this object, and its children is described in another section of this document. The actual persisted XML configuration data is under the Configuration property. The short object description is:

{
  MacroMode: bool,
  IsFirstConfig: bool,
  IsNoConfig: bool,
  Configuration: object,
  MetaInfo: array of object,
  ToolId: int,
  ToolName: string
}

The AfterLoad method provides a way to easily retrieve values from the data items after the Manager has loaded them from the incoming XML configuration.

To implement the Alteryx.Gui.AfterLoad function the user will use the following signature:

window.Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) { /\*...\*/ }

The parameters are:

manager - this is an object which has implemented the SetConfiguration and GetConfiguration functions for you, this way you can use data items and it will handle filling them with data from the tools configuration for you, as well as persisting them in your workflow. It provides more facilities, such as calling a window.Alteryx.Gui.Annotation function for you to provide a workflow canvas annotation for your tool by simply returning a string. It also is used for interacting with the HTML GUI SDK widgets if you are using them, as well as providing an easy API for accessing upstream field and tool information. The manager’s full API is detailed in the full SDK API reference documentation.

AlteryxDataItems - this is an object which has the various data item type constructors on it, so you may new them up from it. The full listing of available data items you will find on this is listed below. Example:

new AlteryxDataItems.SimpleInt('X')

The BeforeGetConfiguration method is executed before GetConfiguration is fired. It provides a way to change the tool’s current configuration data before it is handed to GetConfiguration. The BeforeGetConfiguration method can be useful if you want to change values or the structure of the data to be persisted.

To implement the Alteryx.Gui.BeforeGetConfiguration function the user will use the following signature:

  window.Alteryx.Gui.BeforeGetConfiguration = function (json) { /\*...\*/ }

The parameter is:

json - this is the actual JSON object handed to GetConfiguration which provides the tool’s current configuration data. The full description of this object, and its children is described in another section of this document. The actual persisted XML configuration data is under the Configuration property. The short object description is:

{
  MacroMode: bool,
  IsFirstConfig: bool,
  IsNoConfig: bool,
  Configuration: object,
  MetaInfo: array of object,
  ToolId: int,
  ToolName: string
}

The following shows an example of how to use BeforeGetConfiguration to change the tool’s current configuration data before it is handed to GetConfiguration.

Alteryx.Gui.BeforeGetConfiguration = function (json) {
  return {
    Configuration: {
      alpha: json.Configuration.A
    }
  }
}

Data items need to be given a dataName at construction which indicates the name of the XML element they are associated with in the tools XML configuration. This is specified as the first parameter in the constructor. After constructing a data item, you should add it to the manager unless you do not wish the manager to persist its data to the tool’s XML configuration. Alternatively, you may add it to a DataItemContainer which has already been added to the manager. This will cause the data to be written to and read from under the XML node of the given DataItemContainer. You add a data item to the Manager or a DataItemContainer with the function AddDataItem. A DataItemContainer may be constructed in the same way as a DataItem during BeforeLoad.

If a data item is not added to the manager or DataItemContainer via the AddDataItem method the data will not persist in the tool’s XML configuration.

Data items will do some type conversion on the incoming data, so if you wish to use them, it is suggested that you pull your values off the data items for UI interaction. For instance, the XML may store the string ‘True’ where you wish to use a Boolean, so you would use a SimpleBool and let it load and convert the value from the JSON for you. The way to easily retrieve values from the data items after the manager has loaded them from the incoming XML configuration would be to use the window.Alteryx.Gui.AfterLoad function, which is executed by the Manager after it has completed such loading into data items.

It’s also worth noting, as you are using data items, you must update their values based on your UI controls, typically by using the events available on your controls; UI control events must call setValue on the data items you wish to update from the given UI control. If you do not setValue on your data items, when the tool goes to persist its configuration in your workflow, the data items will simply persist the initial data they were loaded with.

<!DOCTYPE html> 
<html> 
<head> 
  <meta charset="UTF-8"> 
  <title>Location tool</title> 
  <script type="text/javascript"> 
    // This line below is the necessary piece for loading our UI library 
    document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">') 
  </script> 
</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.BeforeLoad = function (manager, AlteryxDataItems, json) { 
    var defaultX = 0 
    var defaultY = 0 
    // Using SimpleInt data items to work with integral values. 
    var xDataItem = new AlteryxDataItems.SimpleInt('X') 
    var yDataItem = new AlteryxDataItems.SimpleInt('Y') 
    // If there is data in your XML already, the 
    // manager will override these values with it, 
    // here we are simply setting defaults in case 
    // there is no current tool configuration yet 
    xDataItem.setValue(defaultX) 
    yDataItem.setValue(defaultY) 

    // Adding the data items to the manager is necessary if you want it 
    // to automatically persist them during GetConfiguration for you 
    // The manager is also window scoped at window.Alteryx.Gui.manager 
    manager.addDataItem(xDataItem) 
    manager.addDataItem(yDataItem) 

    // Every time a user modifies the x value, we must update the data item 
    document.getElementById('locationXValue').onkeyup = function (xTxtBox) { 
      xDataItem.setValue(xTxtBox.target.value) 
    } 

    // Every time a user modifies the y value, we must update the data item 
    document.getElementById('locationYValue').onkeyup = function (yTxtBox) { 
      yDataItem.setValue(yTxtBox.target.value) 
    } 
  } 

  window.Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) { 
    // The manager has filled the data items with values from the configuration now 
    var xDataItem = manager.getDataItem('X') 
    var yDataItem = manager.getDataItem('Y') 

    // Pull the values from the data item, in case they did any type conversion 
    document.getElementById('locationXValue').value = xDataItem.getValue() 
    document.getElementById('locationYValue').value = yDataItem.getValue() 
  } 

    // This function will be called when it tries to persist the data 
    // to give you a way of returning a string to display on the canvas 
  window.Alteryx.Gui.Annotation = function (manager) { 
    var xDataItem = manager.getDataItem('X') 
    var yDataItem = manager.getDataItem('Y') 
    return 'X:' + xDataItem.getValue() + '\nY:' + yDataItem.getValue() 
  } 

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