Use BeforeLoad and AfterLoad with Data Items

Last modified: June 15, 2020

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.


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( }

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

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4.   <meta charset="UTF-8"> 
  5.   <title>Location tool</title> 
  6.   <script type="text/javascript"> 
  7.     // This line below is the necessary piece for loading our UI library 
  8.     document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">') 
  9.   </script> 
  10. </head> 
  11. <body> 
  12. <h1>Location:</h1> 
  13. <br /> 
  14. <label>X:</label><input type="text" id="locationXValue" /> 
  15. <br /> 
  16. <label>Y:</label><input type="text" id="locationYValue" /> 
  18. <script type="text/javascript"> 
  20.   window.Alteryx.Gui.BeforeLoad = function (manager, AlteryxDataItems, json) { 
  21.     var defaultX = 0 
  22.     var defaultY = 0 
  23.     // Using SimpleInt data items to work with integral values. 
  24.     var xDataItem = new AlteryxDataItems.SimpleInt('X') 
  25.     var yDataItem = new AlteryxDataItems.SimpleInt('Y') 
  26.     // If there is data in your XML already, the 
  27.     // manager will override these values with it, 
  28.     // here we are simply setting defaults in case 
  29.     // there is no current tool configuration yet 
  30.     xDataItem.setValue(defaultX) 
  31.     yDataItem.setValue(defaultY) 
  33.     // Adding the data items to the manager is necessary if you want it to automatically persist them during GetConfiguration for you 
  34.     // The manager is also window scoped at window.Alteryx.Gui.manager 
  35.     manager.addDataItem(xDataItem) 
  36.     manager.addDataItem(yDataItem) 
  38.     // Every time a user modifies the x value, we must update the data item 
  39.     document.getElementById('locationXValue').onkeyup = function (xTxtBox) { 
  40.       xDataItem.setValue( 
  41.     } 
  43.     // Every time a user modifies the y value, we must update the data item 
  44.     document.getElementById('locationYValue').onkeyup = function (yTxtBox) { 
  45.       yDataItem.setValue( 
  46.     } 
  47.   } 
  49.   window.Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) { 
  50.     // The manager has filled the data items with values from the configuration now 
  51.     var xDataItem = manager.getDataItem('X') 
  52.     var yDataItem = manager.getDataItem('Y') 
  54.     // Pull the values from the data item, in case they did any type conversion 
  55.     document.getElementById('locationXValue').value = xDataItem.getValue() 
  56.     document.getElementById('locationYValue').value = yDataItem.getValue() 
  57.   } 
  59.     // This function will be called when it tries to persist the data 
  60.     // to give you a way of returning a string to display on the canvas 
  61.   window.Alteryx.Gui.Annotation = function (manager) { 
  62.     var xDataItem = manager.getDataItem('X') 
  63.     var yDataItem = manager.getDataItem('Y') 
  64.     return 'X:' + xDataItem.getValue() + '\nY:' + yDataItem.getValue() 
  65.   } 
  67. </script> 
  68. </body> 
  69. </html> 
Was This Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support.