Skip to main content

Using Data Items with Widgets

Important

The HTML GUI SDK uses outdated technology that limits your extension opportunities. We've built a new Platform SDK using Python and the latest open-source technology to deliver a vastly improved development experience. Go to Platform SDK to get started!

Widgets are available to allow you to create a tool that is consistent with Designer's look and functionality. These widgets are compatible with all lifecycle methods and do not require as much manual configuration. For example, when using widgets, you do not need to manually create data items, attach UI controls to change events to update data, or set a UI control's initial state with AfterLoad.

Note

Widgets and the DOM

If using widgets, do not interact with them through the DOM, as they modify their DOM nodes dynamically on their own.

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>

Place a Widget

Widgets are placed before SetConfiguration is called, as the JavaScript SDK UI library only places widgets at initialization. Do not try to add or modify these tags after the HTML page has finished loading.

Use the tag <ayx></ayx> to place the widget in the body of the page. This tag accepts these attributes:

  • data-ui-props: Holds a case-sensitive JavaScript object string that describes all the properties to set in selecting and configuring the widget. Properties include:

    • type: Required. Identifies which widget to render.

    • widgetId: Used to access the widget. Must be unique across all widgets.

  • data-item-props: Set to automatically create and attach a data item to the widget. Holds a case-sensitive JavaScript object string that describes all the properties to set in selecting and configuring the data item. Properties include:

  • Standard markup attributes, like class or style. The attributes persist after the widget has rendered.

<ayx data-ui-props='{type: "TextBox", widgetId: "bear", placeholder:"Pick a bear"}' data-item-props='{dataName: "chosen-bear", dataType: "SimpleString"}'> </ayx>

Note

data-ui-props and data-item-props Processing

The data-ui-props and data-item-props attributes are processed with a direct JavaScript eval() call. You may directly reference values and objects that live on the window within it.

Manually Bind a Widget

To manually bind an existing data item to a widget, use the bindDataItemToWidget method on the Manager.

window.Alteryx.Gui.Manager.bindDataItemToWidget(window.bearDataItem, ‘bear’)

This ensures the data item's value is persistent and loads correctly from the tool's XML configuration, assuming a data item has been added to the manager or DataItemContainer.

To change the value of the described widget, call the setValue function on the associated data item; the widget also updates. Several things besides data are synchronized from the data item automatically, depending on the chosen data item.

Several common synchronized properties:

  • disabled

  • hidden

  • In the selector data items, optionList.

To alter a widget’s data item props after it has been created automatically by data-item-props, you must get the data item by data name from the Manager:

var dataItemToModify = window.Alteryx.Gui.Manager.getDataItem(dataName) dataItemToModify.setDisabled(true)

Alter a Widget

To alter a widget's UI properties after it has been created, use the setProp method. Do not attempt to alter the widget's data-ui-props on the DOM node after BeforeLoad has started; eval() on these properties only happens at initial page scrape.

window.Alteryx.Gui.Manager.setProp(widgetId, propertyName, newPropertyValue)

To alter a widget's data item properties, retrieve them from manager.getDataItem(dataName).

Use Collections

CheckBox and RadioButton widgets support toggling visibility of nested HTML elements and widgets, so the UI only presents the active selection and its nested contents. To create a collection, place HTML elements instead of an ayx tag.

<ayx data-ui-props='{type: "CheckBox", widgetId: "CheckBox1"}'> <label>Contents of a collection</label> <ayx data-ui-props='{type: "Button", widgetId: "Button1"}'> </ayx>

<!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> 
    <script> 
        // Any widget data-ui-props you wish to create in JavaScript instead of in-line 
        // should be placed in a script tag here in the head, so that the object is alive 
        // on the window, when the widget itself get's processed during SetConfiguration 
        // which happens immediately after the page has completed loading. 
        // If you are referencing a config object then we recommend namespacing your UI to reduce the likelihood of 
        // conflicting with other properties on the window. 
        window.MyGUINamespace = {} 
        window.MyGUINamespace.XWidgetInitialProps = { 
                type: 'TextBox', 
                widgetId: 'X', 
                placeholder: 'X coord value' 
        } 
        window.MyGUINamespace.YWidgetInitialProps = { 
                type: 'TextBox', 
                widgetId: 'Y', 
                placeholder: 'Y coord value' 
        }
    </script> 
</head> 
<body> 

    <h1>Location:</h1> 
    <br /> 
    <label>X:</label> 
    <!-- Note, you may use the data-ui-props to simply reference variables, as it will be eval()ed as JavaScript. --> 
    <ayx data-ui-props='window.MyGUINamespace.XWidgetInitialProps'></ayx> 
    <br /> 
    <label>Y:</label> 
        <ayx data-ui-props='window.MyGUINamespace.YWidgetInitialProps'></ayx> 
        </ayx> 

    <script type="text/javascript"> 
                window.Alteryx.Gui.BeforeLoad = function (manager, AlteryxDataItems, json) {
                // Using SimpleInt data items to work with integral values. 
                var xDataItem = new AlteryxDataItems.SimpleInt('X') 

                manager.bindDataItemToWidget(xDataItem, 'X') 

                // 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) 
                } 

                // 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>
<!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>
    <script>
      // Any widget data-ui-props you wish to create in JavaScript instead of in-line
      // should be placed in a script tag here in the head, so that the object is alive
      // on the window, when the widget itself get's processed during SetConfiguration
      // which happens immediately after the page has completed loading.
      // If you are referencing a config object then we recommend namespacing your UI to reduce the likelihood of
      // conflicting with other properties on the window.
      window.MyGUINamespace = {}
      window.MyGUINamespace.XWidgetInitialProps = {
        type: 'TextBox',
        widgetId: 'X',
        placeholder: 'X coord value'
      }
      window.MyGUINamespace.YWidgetInitialProps = {
        type: 'TextBox',
        widgetId: 'Y',
        placeholder: 'Y coord value'
      }
    </script>
</head>
<body>

  <h1>Location:</h1>
  <br />
  <label>X:</label>
  <!-- Note, you may use the data-ui-props to simply reference variables, as it will be eval()ed as JavaScript. -->
  <ayx data-ui-props='window.MyGUINamespace.XWidgetInitialProps'
       data-item-props='{ dataName: "X", dataType: "SimpleInt" }'>></ayx>
  <br />
  <label>Y:</label>
  <ayx data-ui-props='window.MyGUINamespace.YWidgetInitialProps'
       data-item-props='{ dataName: "Y", dataType: "SimpleInt" }'></ayx>
  </ayx>

  <script type="text/javascript">

  // 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>
In this section: