Using data items with widgets

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.

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

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 the following 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, such as 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"}'>

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)

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