Use BeforeLoad and AfterLoad with Data Items

The BeforeLoad method is compatible with any UI control library. When using BeforeLoad with Supported Data Items, GetConfiguration can handle reading the configuration and SetConfiguration can manage data persistence.

To begin, pull in the JavaScript UI library by adding the following script to your page header. This script uses document.write to allow the window.Alteryx.LibDir to specify where to find the UI library, regardless of where the user installed Designer.

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

Call window.Alteryx.Gui.BeforeLoad method, including the manager, AlteryxDataItems, and json parameters.

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

Within the BeforeLoad method, manually pull information from the UI to the variables using the parameter AlteryxDataItems. Data items should be named to indicate the relationship between the data item and the associated XML element. The XML element's name is passed into the data item constructor as the first parameter. Data items create their own XML nodes unless added to DataItemContainers.

var xDataItem = new AlteryxDataItems.SimpleInt('X')

If you want persistence to be automatically handled, add the data items to manager or to a DataItemContainer that has already been added to the manager. For either process, use the method addDataItem.

manager.addDataItem(xDataItem)

Data items need to be updated with setValue when a user modifies a value or the data items persist the data that was initially loaded.

document.getElementById('locationXValue').onkeyup = function (xTxtBox) { 
   xDataItem.setValue(xTxtBox.target.value) 
}

After BeforeLoad finishes running, the data is stored in the data items. Data items do some type conversion on the incoming data. For example, a simpleBool changes the string 'True' to a Javascript boolean with the value True. The manager can be used from the AfterLoad method to easily retrieve the stored data, at which point you can use getValue() to retrieve the value from the converted data and use that value to set the UI control's initial value.

Assign the AfterLoad method, including the manager and AlteryxDataItems parameters.

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

Use getValue() to retrieve the value from the data stored in a data item.

document.getElementById('locationXValue').value = xDataItem.getValue()

You can assign BeforeGetConfiguration, which allows you to change the values or structure of the data before passing the information to GetConfiguration.

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

Another option is to create an Annotation. Using Annotation, you can return a string that displays on the canvas. This can be used as a confirmation or error message.

window.Alteryx.Gui.Annotation = function (manager) {...}

Executable example


<!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>