Working with the ContentHead control

In the configuration page, the ContentHead control includes the DialogLoad user control, which supports configuration data access and manipulation, and a static client script block that contains necessary JavaScript code for reading and writing configuration settings, and for registering configuration property sections.

Working with the DialogLoad user control
Reading and writing configuration settings
Registering configuration property sections
Extending the ContentHead control

For more information about the ContentHead control, see Creating configuration pages.

Working with the DialogLoad user control

The DialogLoad user control provides a range of support functionality, including:

Initialization support for the configuration settings dialog
Support functions for workflow variables, such as updating workflow variable references in user controls and renaming workflow variables.
SharePoint registration of CSS style sheets needed by the configuration settings dialog

No configuration is necessary, beyond ensuring that the DialogLoad user control is the first child of the ContentHead control.

Reading and writing configuration settings

The configuration page reads and writes configuration data by using two JavaScript functions, named TPARetrieveConfig and TPAWriteConfig, respectively. These two functions are included in the configuration page as part of a static client script block in the ContentHead control. The configuration data is stored as an XML-serialized NWActionConfig object, in a global XML DOM object named configXml accessible to both functions. The JavaScript script referenced by the DialogLoad user control, included in the ContentHead control, handles the creation and persistence of the configXml object.

Using the TPARetrieveConfig function

The TPARetrieveConfig function is invoked by the Workflow designer when the configuration settings dialog for the workflow action is displayed in the Workflow designer. The intended purpose of the function is to retrieve configuration data from the workflow action and populate the user controls on the configuration page. You can use XPath queries to retrieve the values of configuration settings from the configXml object, depending on the format of the configuration setting.

Retrieving primitive values

For most scalar configuration settings, you need to retrieve the value of the PrimitiveValue property from the ActionParameter object for that configuration setting, and then set the appropriate property for the corresponding user control with that value. The following XPath query demonstrates how to retrieve the primitive value of a configuration setting from configXml, where <Name> is the name of the configuration setting:

/NWActionConfig/Parameters/Parameter[@Name='<Name>']/PrimitiveValue/@Value

You can use the EnsurePrimitiveValueNode JavaScript helper function to avoid errors when retrieving configuration settings that contain primitive values, by ensuring that the configuration setting exists in the configuration XML prior to referencing the element.

The following example illustrates how to retrieve a configuration setting from configXml and populate a SingleLineInput user control named txtSample on a configuration page.

function TPARetrieveConfig()
{
    // Set the value of a SingleLineInput control with the value of its corresponding
    // configuration setting.
    
    // Ensure that the configuration setting exists.
    EnsurePrimitiveValueNode(configXml, "Sample", "String");
    
    // Get a reference to the control for the configuration setting.
    ctlSample = document.getElementById("<%= txtSample.ClientID %>");

    // Set the value of the control to the value of the configuration setting.
    ctlSample.value = configXml.selectSingleNode(
        "/NWActionConfig/Parameters/Parameter[@Name='Sample']/PrimitiveValue/@Name").text;    
}

Using the TPAWriteConfig function

The TPAWriteConfig function is invoked by the Workflow designer when a user saves the configuration settings by clicking the Save button in the ribbon for the configuration settings dialog in Workflow designer. The intended purpose of the function is to retrieve configuration data from the workflow action and populate the user controls on the configuration page.

Writing primitive values

As with TPARetrieveConfig, the TPAWriteConfig function uses the configXml object to store configuration settings. You can use the same XPath query to set the value of a configuration setting, after retrieving it from its corresponding user control. You can also, if desired, perform validation

The following example illustrates how to write a value from a SingleLineInput user control named txtSample to the corresponding configuration property in configXml.

function TPAWriteConfig()
{
    // Get a reference to the control for the configuration setting.
    ctlSample = document.getElementById("<%= txtSample.ClientID %>");

    // Ensure that the configuration setting exists.
    EnsurePrimitiveValueNode(configXml, "Sample", "String");

    // Set the value of the configuration setting to the value of the control.
    // You can add code to validate values first. If validation fails, ensure that
    // the function returns false.
    ctlSample.value = configXml.selectSingleNode(
        "/NWActionConfig/Parameters/Parameter[@Name='Sample']/PrimitiveValue/@Name").text = 
        ctlSample.value;    

    // Return true if the configuration has been successfully updated; otherwise, return false.
    return true;
}

Reading and writing data for user controls

Some controls, such as the RTE control, require the use of JavaScript helper functions to get and set their values. For more information, see Working with controls.

Registering configuration property sections

The static client script block in the ContentHead control is also used to register ConfigurationPropertySection controls, so that they can be initially displayed or hidden when the Action button in the Settings group of the ribbon for the configuration settings dialog is toggled on or off.

When the configuration settings dialog is displayed by the Workflow designer, the dialog can be displayed in one of three views, depending on which button is toggled in the Settings group of the ribbon for the dialog:

Action

This view displays the contents of the configuration page in the configuration settings dialog.
Labels

This view displays the labels page in the configuration settings dialog. For more information about configuring labels for a workflow action, see the Nintex Workflow 2013 product documentation.
Common

This view displays the common settings page in the configuration settings dialog. For more information about the common settings for a workflow action, see the Nintex Workflow 2013 product documentation.

Each ConfigurationPropertySection control in the configuration page can be displayed or hidden, depending on the requirements of the workflow action, but the initial visibility of these controls when the Action button is toggled on is determined by registering the controls in a global array of Boolean values, named dialogSectionsArray. When the Action button is toggled on, the Boolean value for each control in the array determines whether that control is initially visible. If you have only one ConfigurationPropertySection control in the configuration page, it must be registered with a value of true; otherwise, the configuration page will not be displayed.

For example, if you have one ConfigurationPropertySection, named MainControls1, then the following JavaScript code demonstrates how to register it with the dialogSectionsArray global array so that the control is initially visible when the Action button is toggled on.

// Register the ConfigurationPropertySection on the page.
// Set the value to true to initially show the section; otherwise, set it to
// false to initially hide the section.
onLoadFunctions[onLoadFunctions.length] = function () {
    dialogSectionsArray["<%= MainControls1.ClientID %>"] = true;
};

Extending the ContentHead control

You can add whatever JavaScript is needed for the configuration page within the static client script block. For example, you could add functions that can be called by the TPAWriteConfig function to validate configuration settings prior to writing them to configXml, or that enables or disables configuration property template controls when the value of a given user control is changed.