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">')

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.


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) { 

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) {...}