Skip to main content

Lifecycle Methods

Importante

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!

Lifecycle Methods

The HTML SDK provides five lifecycle methods that can be used in a variety of patterns to create tools. The lifecycle methods load in this order:

  • SetConfiguration: Executed when the tool is clicked on. Used to obtain the tool's configuration as soon as the tool finishes loading the HTML.

SetConfiguration: function (currentToolConfiguration){...}

Parameters

currentToolConfiguration: The tool's configuration from the property Configuration. Configuration is constructured by convertingsystem.Xml.XmlElementto JSON using theJsonConvert.SerializeObjectmethod from NewstonSoft Json.Net. See Json.NET documentation. Seeconverter source file.

  • BeforeLoad: Executed before the data stores are loaded. Used to manually configure data stores.

window.Alteryx.Gui.BeforeLoad = function (manager, AlteryxDataItems, json) {...}

Parameters

manager: An object that implements theSetConfigurationandGetConfigurationfunctions, managing data items, their content from the configuration, and their persistance in the workflow. The manager also:

  • calls the window.Alteryx.Gui.Annotation function, which provides a workflow canvas annotation for your tool by returning a string.

  • interacts with the HTML GUI SDK widgets.

  • provides an easy API for accessing upstream field and tool information.

The manager’s full API is detailed in theAPI reference documentation.

AlteryxDataItems: An object with various data item type constructors on it, so you may new them up from it. For the full listing of supported data items, seeSupported Data Items.

new AlteryxDataItems.SimpleInt('X')

json: An object containing the actual JSON that provides the tool’s current configuration data. The actual persisted XML configuration data is under the Configuration property. The short object description is:

{
        MacroMode: bool,
        IsFirstConfig: bool,
        IsNoConfig: bool,
        Configuration: object,
        MetaInfo: array of object,
        ToolId: int,
        ToolName: string
}
  • AfterLoad: Executed after the data stores have been loaded. Used to trigger application logic. Retrieves values from data items after the manager has loaded values from the incoming XML configuration.

window.Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) {...}

Parameters

manager: An object that implements theSetConfigurationandGetConfigurationfunctions, managing data items, their content from the configuration, and their persistance in the workflow.

The manager also...

  • Calls the window.Alteryx.Gui.Annotation function, which provides a workflow canvas annotation for your tool by returning a string.

  • Interacts with the HTML GUI SDK widgets.

  • Provides an easy API for accessing upstream field and tool information.

The manager’s full API is detailed in theAPI reference documentation.

AlteryxDataItems: An object with various data item type constructors on it, so you may new them up from it. For the full listing of supported data items, seeSupported Data Items.

new AlteryxDataItems.SimpleInt('X')

json: An object containing the actual JSON that provides the tool’s current configuration data. The actual persisted XML configuration data is under the Configuration property. The short object description is:

{
        MacroMode: bool,
        IsFirstConfig: bool,
        IsNoConfig: bool,
        Configuration: object,
        MetaInfo: array of object,
        ToolId: int,
        ToolName: string
}
  • AfterLoad: Executed after the data stores have been loaded. Used to trigger application logic. Retrieves values from data items after the manager has loaded values from the incoming XML configuration.

window.Alteryx.Gui.AfterLoad = function (manager, AlteryxDataItems) {...}

Parameters

manager: An object that implements the SetConfiguration and GetConfiguration functions, managing data items, their content from the configuration, and their persistence in the workflow.

The manager also...

  • Calls the window.Alteryx.Gui.Annotation function, which provides a workflow canvas annotation for your tool by returning a string.

  • Interacts with the HTML GUI SDK widgets.

  • Provides an easy API for accessing upstream field and tool information.

The manager’s full API is detailed in the API reference documentation.

AlteryxDataItems: An object with various data item type constructors on it, so you may new them up from it. For the full listing of supported data items, see Supported Data Items.

new AlteryxDataItems.SimpleInt('X')
  • BeforeGetConfiguration: Executed before theGetConfigurationevent is fired. Allows for current configuration data to be changed before obtaining the tool configuration on deselection. Used to change the values or the structure of the persisted data.

window.Alteryx.Gui.BeforeGetConfiguration = function (json) {...}

Parameters

json: An object containing the actual JSON that provides the tool’s current configuration data. The actual persisted XML configuration data is under the Configuration property. The short object description is:

{
        MacroMode: bool,
        IsFirstConfig: bool,
        IsNoConfig: bool,
        Configuration: object,
        MetaInfo: array of object,
        ToolId: int,
        ToolName: string
}
  • GetConfiguration: Executes as the final action before a tool is deselected, obtains the tool configuration from the GUI.

GetConfiguration: function () {...}

UI Creation Patterns

There are several methods available to creating a tool. Evaluate what your users require of your tool before determining what method of creation you want to use.

If the tool is filling in an existing UI, it does not need to persist configuration between uses. If the tool has configuration settings that persist, but are not displayed to a user, the tool does not need to synchronize data between UI controls and the configuration persistence.

UI Creation Pattern

Tool Automatically Loads and Persists Your Configuration

Tool Automatically Synchronizes Data Between UI Controls and Configuration Persistence

Use Only SetConfiguration and GetConfiguration

No

No

Use BeforeLoad and AfterLoad with Data Items

Yes

No

Using Data Items with Widgets

Yes

Yes