You are here:

Using data items with widgets

For the tool developer who doesn’t want to deal with creating their own UI controls to interact with their tool’s workflow configuration, we have created a set of widgets which will update data items associated with them for you. There’s a myriad of benefits to using these, including they blend naturally with the look and feel of Alteryx, and are used by the Alteryx team for their own tools, so have been tested and proven to work for the task.

To use these, you must pull in the HTML GUI SDK library as described in the data item section above. You may create your data items, and add them to the manager in the BeforeLoad function just as above, but it’s not required with the widgets. You have the same lifecycle methods described above, such as BeforeLoad, AfterLoad, and Annotation. However, when using the widgets, you do not need to create the data items yourself, attach to the UI controls change events to update the data items, or even set the UI controls initial value from the data items in AfterLoad as you would if you weren’t using the widgets.

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

Placing a widget on your page

To place widgets in your page, use the custom tag <ayx></ayx> with the required data-ui-props attribute to describe the widget you wish to place. If you want a data item created and attached to it automatically, add the data-item-props attribute as well. As this tag will have the actual widget’s HTML rendered as a child to it, this may not be a self-closing tag. It also is allowable to place any standard markup attributes on it such as class or styling et al, and it will persist just as though it were any non-standard tag even after the widget has rendered as child to the element.

Widgets must be on your page before SetConfiguration is called, as the JavaScript SDK UI library will only search for these tags once at initialization to place the widgets on your page. Do not try to add or modify these tags after the HTML page has finished loading.

The data-ui-props and data-item-props attributes hold a case-sensitive JavaScript object string that describes all the properties to set in selecting and configuring the widget and data item. At a minimum, you need the type property in data-ui-props, as this will identify which widget from the library to render, and the widgetId property which is used within the SDK API’s for accessing the widget. The minimum for data-item-props is a dataName string, optionally a dataType string will specify the data item to construct. Some data items allow more props, these are detailed in the constructors of each data item in the detailed SDK API reference documentation.

The widgetId property must be unique across widgets.

Simple example:

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

The way the data-ui-props and data-item-props attributes are processed is with a direct JavaScript eval() call. This is worth remembering, because you may directly reference values and objects that live on the window within it. For example:


…
<script>
  window.MyGUINameSpace.BearWidgetInitialUiProps = {
    type: 'TextBox',
    widgetId: 'bear',
    placeholder: 'Pick a bear'
  }

  window.MyGUINameSpace.BearWidgetInitialItemProps = {
    type: 'TextBox',
    widgetId: 'bear',
    placeholder: 'Pick a bear'
 }
  </script>
</head>
<body>
  <label>Bear:</label>
  <ayx data-ui-props='window.MyGUINameSpace.BearWidgetInitialUiProps'
       data-item-props='window.MyGUINameSpace.BearWidgetInitialItemProps'>
  </ayx>
…

To alter a widget’s UI props after it has been created, you can use:


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

For example, given the widget example above, you could make the textbox placeholder text give better advice with:


window.Alteryx.Gui.Manager.setProp(‘bear’, ‘placeholder’, ‘Don\’t pick a bear, they\’re dangerous.’)

Do not attempt to alter the data-ui-props or data-item-props object of a widget on the DOM node after BeforeLoad has started, these properties are only eval()’ed at initial page scrape. You must use setProp, as described above, or for data related behaviors, to modify the properties of a widget’s data item retrieved from manager.getDataItem(dataName).

Collections: CheckBox and RadioButton widgets support toggling the visibility of nested HTML elements and widgets. In the following example the label and button widget will only be displayed when the CheckBox widget is checked.

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

The following is an example of collections associated with a set of RadioButton widgets. Only the selected radio button will display its nested collection of elements.

<ayx data-ui-props='{type: "RadioButton", widgetId: "RadioButton1", option: {value: "RadioValue1", label:"Radio Button 1"}}'>
  <label>Contents of radio button 1 collection</label>
  <ayx data-ui-props='{type: "Button", widgetId: "Button1"}'>
</ayx>
<ayx data-ui-props='{type: "RadioButton", widgetId: "RadioButton2", option: {value: "RadioValue2", label:"Radio Button 2"}}'>
  <label>Contents of radio button 2 collection</label>
  <ayx data-ui-props='{type: "Button", widgetId: "Button2"}'>
</ayx>

Binding a data item to a widget

The real benefits to using widgets, as described above, is you may easily attach data items to the widgets. You may do this by using the bindDataItemToWidget method on the Manager, or by using the data-item-props as described above.


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

A simple attachment to a widget as such will ensure that the data item’s value is appropriately filled based on the user’s interactions with the widget, and the widgets value is loaded from the tools XML configuration correctly due to the data item.

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.

If you wish to change the value of the described widget, you should call the setValue function on the associated data item, and the widget will update in accordance. As the data item’s value is synchronized with the widget, this ensures the tool’s configuration will be persisted into the workflow with the appropriate XML from the UI. There are also other things synchronized from the data item for you automatically, depending on the data item you choose. A couple common propertys that get synchronized are disabled, hidden, and in the selector data items optionList. For more details of data item properties, you may read the detailed SDK API reference documentation.

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)

Using data items as well as widgets 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> 
    <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"> 
 
    // 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>

Using data items as well as widgets example with widgets referencing JS variables

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