One of the many benefits of Custom Nodes is the ability to manage their settings and configuration from within the GlobalCapture designer.  The node.html file should be added to any Custom Node package.

Building a node.html File

The Custom Node user interface displayed in the Admin panel and Workflow designer is sourced from a file within your Custom Node called "node.html". This HTML file is responsible for the visual interface, as well as the establishment and control of any Custom Node Settings that can be retrieved by your Custom Node assembly code.

If you wish to display a Custom Node user interface, you must design a node.html file and include it in your Custom Node.

Modal Height

A fixed height can be set for the node.html by adding "node-height" attribute. By default, it is set at 260px. For example:

<body node-height="200"></body>
CODE

CSS References

Custom styling can be referenced from your node.html like so:

<link rel="stylesheet" href="styles.css">
CODE

This CSS link will target a .css file within your Custom Node called "styles.css".  As with any cascading style setup, the CSS files are loaded and cascaded in the order in which they are linked in your HTML.

Defining a Setting

In order for you to utilize Custom Node settings from your Custom Node assembly code, a link must be established between HTML elements and corresponding settings accessible within the Settings class in the Square9.CustomNode SDK.

To do this, add an HTML attribute "setting" with an attribute value equal to the desired name of that setting.

The following example sets the groundwork for an input that controls a setting titled "Name".


<type="text" setting="Name">

Setting Types

HTML elements tied to settings can take different forms, such as numerical inputs, or checkboxes. Considering this, you must also define a setting-type attribute on any setting that indicates the data type of that setting.

This data type is strictly enforced when gathering and setting data to the HTML input, as well when interacted with through methods in the Settings class in the Square9.CustomNode SDK.

There are four different setting types:

setting-type="string"

The string type setting will accept any string value, sourced from the "value" property of the element to which it is attached:

<input type="text" placeholder="Name" setting="Name" setting-type="string">
CODE

setting-type="int"

The int type setting will accept any whole number values sourced from the "value" property of the element to which it is attached:

<input type="number" setting="Age" setting-type="int">
CODE

Seen below, groups of radio buttons are also supported for int and string type settings.  

<input type="radio" name="answer" setting="enum" setting-type="int" value="1">
<input type="radio" name="answer" setting="enum" setting-type="int" value="2">
<input type="radio" name="answer" setting="enum" setting-type="int" value="3">
CODE

setting-type="boolean"

The boolean type setting is attributable to checkbox elements, and will accept values sourced from the "checked" property of those checkbox elements:

<input type="checkbox" setting="Insured" setting-type="boolean">
CODE

setting-type="list"

The list type setting is designed to gather multiple values together onto one setting. This is achievable in two ways:

Multiple Settings

If multiple settings are defined with the same setting name, and all with setting-type="list", then the ListValue of the setting retrieved from the Settings class in the Square9.CustomNode SDK will contain these values.

<input type="text" setting="Attributes" setting-type="list">
<input type="text" setting="Attributes" setting-type="list">
<input type="text" setting="Attributes" setting-type="list">
CODE
Textbox With Separator

A single input can capture multiple list values by specifying a "separator" attribute. The following input will gather multiple values separated by a comma:

<input type="text" setting="Attributes" setting-type"list" separator=",">
CODE

As values are parsed and separated from this input, extra whitespace is trimmed from each value.

Repeat Lists

Using the "repeat-list" tag you can duplicate any element in the html template based on how many setting-type="list" values are associated within them.  This this example this "row" will be cloned for as many inboxes and archives exist in the default or saved settings.  When the HTML template render these values will be pre-populated into the duplicated inputs.

<div class="row" repeat-list>
	<div class="col-xs-6 form-group required">
		<label for="inboxes" class="control-label">Source Inbox</label>
		<select id="inboxes" class="form-control" data-toggle="tooltip" setting="InboxName" setting-type="list" workflow-inboxes>
			<option value=""></option>
		</select>
	</div>
	<div class="col-xs-6 form-group required">
		<label for="archives" class="control-label">Destination Archive</label>
		<select id="archives" class="form-control" data-toggle="tooltip" setting="ArchiveName" setting-type="list" workflow-archives setting-hidden>
			<option value=""></option>
		</select>
	</div>
</div>
CODE

It's important to note that only setting-type="list" setting are supported in these tags.  Another setting types are not advised.

Required Settings

A "required" attribute can be added to any setting. Settings with this attribute must contain values for the interface to be considered valid and the values saved:

<input type="text" setting="Path" setting-type="string" required>
CODE

Hidden Settings

A "setting-hidden" attribute can be added to any setting. Settings with this attribute will not appear in the node info panel when selected on the workflow design surface.  This can be useful for password or other sensitive information:

<input type="text" setting="Path" setting-type="string" setting-hidden>
CODE

List Population

When defining your setting inputs, you may find it useful to use contextual elements such as fields, properties, user, or archives to populate a drop down.  Naturally doing this dynamically can provide an more natural experience for anyone using the custom node.  By adding the following attribute to your select tag you can prepopulate your selections.

  • workflow-properties
    • Creates a drop down of all current properties added to the workflow.
  • workflow-fields
    • GA only attribute, that allows for all current GS catalog fields to be populated.
  • workflow-users
    • Creates a list of all current users and groups available in the system.  This includes Square 9 Users.
  • workflow-archives
    • GA only attribute, populates your select with a list of all current GS archives.
  • workflow-inboxes
    • GA only attribute, populates your select with a list of all current GS inboxes.


<select id="test" data-toggle="tooltip" required workflow-properties setting="property" setting-type="string" class="form-control">
	<option value=""></option>
</select>
CODE

NOTE: As this dropdown is populated with data dependent on the workflow being used, it is not available for population in the Node management settings HTML template panel for default values.

Getting Started

Custom nodes ... can use HTML ... this will sound nice

This guide assumes the reader has a working knowledge of the HTML language, as well as a basic understanding of web design. 

Building a node.html File

The Custom Node user interface displayed in the Admin panel and Workflow designer is sourced from a file within your Custom Node called "node.html". This HTML file is responsible for the visual interface, as well as the establishment and control of any Custom Node Settings that can be retrieved by your Custom Node assembly code.

If you wish to display a Custom Node user interface, you must design a node.html file and include it in your Custom Node.

Modal Height

A fixed height less then 260px can be set for the node.html by adding "node-height" attribute. For example:

<body node-height="200"></body>
CODE

CSS References

Custom styling can be referenced from your node.html like so:

<link rel="stylesheet" href="styles.css">
CODE

This CSS link will target a .css file within your Custom Node called "styles.css".  As with any cascading style setup, the CSS files are loaded and cascaded in the order in which they are linked in your HTML.

Defining a Setting

In order for you to utilize Custom Node settings from your Custom Node assembly code, a link must be established between HTML elements and corresponding settings accessible within the Settings class in the Square9.CustomNode SDK.

To do this, add an HTML attribute "setting" with an attribute value equal to the desired name of that setting.

The following example sets the groundwork for an input that controls a setting titled "Name".


<type="text" setting="Name">

Setting Types

HTML elements tied to settings can take different forms, such as numerical inputs, or checkboxes. Considering this, you must also define a setting-type attribute on any setting that indicates the data type of that setting.

This data type is strictly enforced when gathering and setting data to the HTML input, as well when interacted with through methods in the Settings class in the Square9.CustomNode SDK.

There are four different setting types:

setting-type="string"

The string type setting will accept any string value, sourced from the "value" property of the element to which it is attached:

<input type="text" placeholder="Name" setting="Name" setting-type="string">
CODE

setting-type="int"

The int type setting will accept any whole number values sourced from the "value" property of the element to which it is attached:

<input type="number" setting="Age" setting-type="int">
CODE

Seen below, groups of radio buttons are also supported for int and string type settings.  

<input type="radio" name="answer" setting="enum" setting-type="int" value="1">
<input type="radio" name="answer" setting="enum" setting-type="int" value="2">
<input type="radio" name="answer" setting="enum" setting-type="int" value="3">
CODE

setting-type="boolean"

The boolean type setting is attributable to checkbox elements, and will accept values sourced from the "checked" property of those checkbox elements:

<input type="checkbox" setting="Insured" setting-type="boolean">
CODE

setting-type="list"

The list type setting is designed to gather multiple values together onto one setting. This is achievable in two ways:

Multiple Settings

If multiple settings are defined with the same setting name, and all with setting-type="list", then the ListValue of the setting retrieved from the Settings class in the Square9.CustomNode SDK will contain these values.

<input type="text" setting="Attributes" setting-type="list">
<input type="text" setting="Attributes" setting-type="list">
<input type="text" setting="Attributes" setting-type="list">
CODE
Textbox With Separator

A single input can capture multiple list values by specifying a "separator" attribute. The following input will gather multiple values separated by a comma:

<input type="text" setting="Attributes" setting-type"list" separator=",">
CODE

As values are parsed and separated from this input, extra whitespace is trimmed from each value.

Repeat Lists

Using the "repeat-list" tag you can duplicate any element in the html template based on how many setting-type="list" values are associated within them.  This this example this "row" will be cloned for as many inboxes and archives exist in the default or saved settings.  When the HTML template render these values will be pre-populated into the duplicated inputs.

<div class="row" repeat-list>
	<div class="col-xs-6 form-group required">
		<label for="inboxes" class="control-label">Source Inbox</label>
		<select id="inboxes" class="form-control" data-toggle="tooltip" setting="InboxName" setting-type="list" workflow-inboxes>
			<option value=""></option>
		</select>
	</div>
	<div class="col-xs-6 form-group required">
		<label for="archives" class="control-label">Destination Archive</label>
		<select id="archives" class="form-control" data-toggle="tooltip" setting="ArchiveName" setting-type="list" workflow-archives setting-hidden>
			<option value=""></option>
		</select>
	</div>
</div>
CODE

It's important to note that only setting-type="list" setting are supported in these tags.  Another setting types are not advised.

Required Settings

A "required" attribute can be added to any setting. Settings with this attribute must contain values for the interface to be considered valid and the values saved:

<input type="text" setting="Path" setting-type="string" required>
CODE

Hidden Settings

A "setting-hidden" attribute can be added to any setting. Settings with this attribute will not appear in the node info panel when selected on the workflow design surface.  This can be useful for password or other sensitive information:

<input type="text" setting="Path" setting-type="string" setting-hidden>
CODE

List Population

When defining your setting inputs, you may find it useful to use contextual elements such as fields, properties, user, or archives to populate a drop down.  Naturally doing this dynamically can provide an more natural experience for anyone using the custom node.  By adding the following attribute to your select tag you can prepopulate your selections.

  • workflow-properties
    • Creates a drop down of all current properties added to the workflow.
  • workflow-fields
    • GA only attribute, that allows for all current GS catalog fields to be populated.
  • workflow-users
    • Creates a list of all current users and groups available in the system.  This includes Square 9 Users.
  • workflow-archives
    • GA only attribute, populates your select with a list of all current GS archives.
  • workflow-inboxes
    • GA only attribute, populates your select with a list of all current GS inboxes.


<select id="test" data-toggle="tooltip" required workflow-properties setting="property" setting-type="string" class="form-control">
	<option value=""></option>
</select>
CODE

NOTE: As this dropdown is populated with data dependent on the workflow being used, it is not available for population in the Node management settings HTML template panel for default values.