Overview of Forms

Forms allow end users to enter information for the workflow to operate on. For example, a workflow that locates an address for the user would include a form where the user enters the address.

In addition to gathering textual information like addresses, you can use forms to get dates, numbers, map locations (geometries), and more from the user, or to get the user to select from arbitrary items that are defined in the workflow or retrieved from a database when the workflow runs.

Form Elements

Form elements are the building blocks of forms. When you design a form, the Toolbox contains form elements instead of activities. To build the form, you drag form elements from the Toolbox to the design surface and place them in the order that you want them to appear to the end user. You then configure each element's properties to customize the behavior and appearance of the element.

The type of a property defines what types of values the property can have. For example, the Visible property's type is Boolean, which means its value can be true or false. Perhaps the most common type is string, which means that the property's value is text. Some properties have more than one type. For example, the value property can be any type.

In a workflow, you can use the Get Form Element Property activity to find out the current value of a particular property. You can change the value of a particular property using the Set Form Element Property activity.

Types of Form Elements

Geocortex Workflow has the following customizable form elements:

Events

In Geocortex Workflow, an event is something that happens in a form. This could be an action by the user, like a button click, or a step in the form's life cycle, like the validation step after the user has submitted the form.

Events allow you to monitor what is happening in the form and customize how the workflow responds. For example, you could monitor a checkbox and show additional form elements if the user selects the checkbox. To customize the response, you add a subworkflow that defines the custom behavior. When the event occurs ("fires"), the subworkflow runs.

Adding an event subworkflow overrides Geocortex Workflow's default behavior for handling events. Having an event subworkflow is your way of telling the workflow that you want to take control of how the event is handled.

Sometimes, you may want to have both custom behavior and the default behavior. In this case, you can add a Propagate Form Event activity to the event subworkflow. The Propagate Form Event activity instructs the workflow to perform the default behavior after the event subworkflow completes.

Different types of form elements support different types of events. For example, radio groups have load and change events, whereas button bars have load, click, and submit events. Each element in a form has its own events. For example, if a form has two radio groups, each radio group has its own load and change events.

Types of Events

Geocortex Workflow has the following types of events:

For more information about a particular event, refer to the documentation for the form element.

Some events can fire multiple times for the same form element, causing the event subworkflow to run multiple times. For this reason, we recommend that you make sure that event subworkflows are not computationally intensive or long running.

Add a Form to a Workflow

To add a form to a workflow, you use the Display Form activity. Like other activities, the Display Form activity has properties and inputs that you configure for it. In addition, the Display Form activity has a built-in designer that you use to build forms. To open the designer, double-click the Display Form activity in the flowchart.

When you create a new form, the form has two elements—one for the form's title and one for the Submit and Cancel buttons. These elements are automatically displayed at the top and bottom of the form respectively. When you add elements to the form, add them in between these two elements, in the order that you want them to appear to the user.

To configure a form element, select the element in the preview. The element's settings open at the right.

New form, showing the form elements that you use to build forms, a preview of the form, and the selected element's settings

Main Steps to Configure a Form

The main steps to configure a form are:

  1. Drag a Display Form activity to the design surface.

  2. Double-click the Display Form activity to open it for editing.

  3. Build the form by adding and configuring form elements:

    1. Drag a form element from the Toolbox and drop it in the preview area.

      The preview shows the elements in the order they will appear when the workflow runs. You can drag the elements within the preview to re-order them.

    2. Click the form element to select it.

      The element's settings open.

    3. Configure the element's settings.

      For information about the settings for a particular form element, refer to the section about that element.

  4. Add events:

    1. Select a form element.

    2. In the Events area, click the arrow to show the events.

    3. Click Add beside the event that you want to customize.

      A blank subworkflow opens.

    4. Build the subworkflow the same way you build the main workflow—drag activities from the Toolbox to the design surface, configure their settings, and connect them into a flowchart.

    5. When you have completed the subworkflow, click Display Form in the breadcrumbs to return to the form preview.

      You can re-open the subworkflow from the element's Actions menu or by clicking Edit in the Properties panel.

    6. Repeat these steps for each event that you want to add.
  5. When you are satisfied with the form, click Start in the breadcrumbs to return to the main workflow.

Add Formatting and Hyperlinks to Forms

You can improve the appearance and effectiveness of your forms by formatting the text that you display to the user and including hyperlinks in the text. Geocortex Workflow Designer supports Markdown, a simple method of adding formatting like headers, lists, bold text, hyperlinks, and more.

To use Markdown, when you configure the text that you want to format, you precede or surround the text with the Markdown characters for the formatting you want. For example, if you surround a sentence with asterisks (*), (*This sentence is bold*), then the sentence will appear bold in the form (This sentence is bold).

The form preview shows the formatted text, so you can see what the formatting will look like in the running workflow.

If you want to use a Markdown character as itself in a setting that supports Markdown, put a backslash (\) before the character. For example, if you want a hash at the beginning of a line (#10 Downing Street), enter \# at the beginning of the line (\#10 Downing Street). This prevents the hash from being interpreted as the Markdown character for a heading.

Some formats require more than one line. For example, a list with three items requires three lines. However, some settings in Workflow Designer do not allow you to enter more than one line. For example, you cannot enter multiple lines into a Title property. If pressing Enter does not go to a new line when you are configuring a setting, then the setting only allows one line.

If the information that you want to display requires more than one line, add a Text element to your form. The Text element's Description property allows you to enter as many lines as you want.

To check whether a particular setting supports formatting, hover the pointer over the setting's help icon in the Properties panel. The help indicates whether the setting supports formatting. For quick access to the Formatting to Use in Forms table, click the More... hyperlink.

Formatting to Use in Forms

Format

 

Example

Description

 

 

This configuration...

Displays as...

Italics

This is *italics.*

or

This is _italics._

This is italics.

To display italics text, put an asterisk (*) or an underscore (_) at each end of the text.

Bold

This is **bold.**

or

This is __bold.__

This is bold.

To display bold text, put two asterisks (**) or two underscores (__) at each end of the text.

Headings

# Main Heading

## Second-level Heading

### Third-level Heading

Main Heading

Second-level Heading

Third-level Heading

To display a top-level heading, put a hash (#) at the beginning of the paragraph. Put two hashes (##) for second-level headings, three hashes (###) for third-level headings, and so on.

Inline Monospace

The site at `https://www.geocortex.com` provides samples.

The site at https://www.geocortex.com provides samples.

To display a single line or part of a line of text in a monospace font and preserve the number of spaces in the original text, put backticks (`) at the beginning and end of the text.

You cannot put Markdown within Inline Monospace text. Characters like asterisks (*), underscores (_), and hashes (#) appear exactly as you enter them in the configuration—they are not interpreted as Markdown characters in Inline Monospace text.

Hyperlink

[Geocortex Website](https://www.geocortex.com)

or

<https://www.geocortex.com>

Geocortex Website

or

https://www.geocortex.com

The pattern to put a hyperlink in the text is:

[link text](URL)

Replace link text with the text that you want to display in the form. Replace URL with the URL that you want to link to. You must include the brackets.

Alternatively, if you want to use the URL as the link text, you can use this pattern:

<URL>

Horizontal Rule

This is a horizontal line.
___

This is a horizontal line.


To enter a horizontal line, type three or more underscores (___) on a new line.

New Line

This is the first line.\
This is the second line.\
This is the third line.

 

This is the first line.
This is the second line.
This is the third line.

To go to a new line, type a backslash (\) and press Enter.

The New Line Markdown has no effect in settings that only allow a single line.

Bulleted List

- First list item
- Second list item
- Third list item

or

* First list item
* Second list item
* Third list item

  • First list item
  • Second list item
  • Third list item

To display a bulleted list, put a dash (-) or an asterisk (*) at the beginning of each list item.

The Bulleted List Markdown will not render a multi-line list in a setting that only allows a single line.

Numbered List

1. This is the first step.
1. This is the second step.
1. This is the third step.

or

1) This is the first step.
1) This is the second step.
1) This is the third step.

1. This is the first step.
2. This is the second step.
3. This is the third step.

To display a numbered list, put a number followed by a period or a closing bracket at the beginning of each step, for example, 1. or 1).

The list starts at whatever number you use in the first step. It doesn't matter what numbers you use in subsequent steps—the numbers will increment by 1.

To end the list, press Enter twice at the end of the last step.

The Numbered List Markdown will not render a multi-line list in a setting that only allows a single line.

Submit a Form

Forms are typically used to gather input from the user. In a typical scenario, the user fills in the form and then submits it. If the input has errors or omissions, the user makes corrections and resubmits the form. This cycle of making corrections and submitting the form is repeated as many times as necessary. When the form is free of errors, the input is ready to be processed. The form closes and the workflow continues running at the next activity after the Display Form activity.

Buttons are used to control form validation and submission. When you configure a button, you specify whether the button causes validation and/or submits (exits) the form. When the user clicks the button:

  1. If the button causes validation, the validation cycle is repeated until the form is error-free.

  2. If the button submits the form, the form closes and the workflow continues running at the next activity after Display Form.

By default, forms have a footer button bar with Submit and Cancel buttons. The Submit button causes validation and submits the form. The Cancel button submits the form without validating the user's input.

Every new form you create has a footer button bar. You can modify the footer button bar's properties (except the Element ID), but you cannot move or delete the button bar. If you do not want your form to have a footer, clear the button bar's Visible checkbox to hide the button bar.

Validate the User’s Input

When the user clicks a button that is configured to cause validation, validation is performed for each element in the form that has validation configured. There are two ways to configure validation for a form element:

In the following screen capture, the user has submitted the form without selecting a state. Because the state is configured to be required, the form will not close until the user enters the state.

Example of a validation message in a form

Example - Subworkflow for a Validate Event

This example illustrates one way to validate an email address in a validate subworkflow. The subworkflow looks like this:

Flowchart for a subworkflow that validates an email address

The validate subworkflow uses a regular expression to compare the user's input to the pattern for a valid email address (), and then branches based on whether the input matches the pattern or not (). If it doesn't match (), the subworkflow sets an error on the input element and the error message displays in red text above the element. If the input does match the pattern (), the subworkflow clears any error that was previously set on the input element.

Error message on the Email Address text box

To configure a validate subworkflow that tests the validity of an email address:

  1. Add a text box with a validate event:

    1. Edit a Display Form activity.

    2. Add a text box to the form and change its title to Email Address.

    3. Select the text box to show the Properties panel, and then click the arrow beside Events to show the events.

    4. Click Add beside the validate event.

      A blank Event subworkflow opens.

  2. Test whether the input is valid:

    1. Drag a Regular Expression Matches activity to the design surface and connect it to the Event block.

    2. In the Text input, type an equals sign (=) followed by a reference to the user's input, for example, $form1.state.textBox1.value.

    3. In the Pattern input, type or paste the regular expression that defines the pattern for the email address, for example:

      ^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)

  3. Branch based on whether the input is valid:

    1. Drag an If activity to the design surface and connect it to the Regular Expression Matches activity.

    2. Set the Condition input to the result of the Regular Expression Matches activity, for example, =$regexMatches1.result.

  4. Invalid input:

    1. Drag a Set Form Element Error activity to the design surface and connect it to the If activity's False branch.

    2. Set the Element ID input to the Element ID of the text box.

    3. Set the Error input to the error message that you want to display above the text box, for example, Email address is invalid.

  5. Valid input:

    1. Drag a Clear Form Element Error activity to the design surface and connect it to the If activity's True branch.

      Whenever you use a Set Form Element Error activity, make sure you also use a Clear Form Element Error activity to clear the error. Otherwise the form may get stuck in an invalid state.

    2. Set the Element ID input to the Element ID of the text box.

  6. Click Display Form in the breadcrumbs to return to the form preview.

    You can re-open the subworkflow from the text box's Actions menu or by clicking Edit in the Properties panel.

Access User Inputs

After the user has entered information into a form and submitted the form, you can use the user's inputs in other activities. To access a form's inputs, you use the form's state output in an expression. The state output gives you access to the individual inputs that the user entered in the form. An expression to access a form element looks like this:

$formID.state.elementID.value

The parts of the expression are:

See also...

Example - Enter an Expression to Access Another Activity’s Output

Close a Form in Workflow Designer

To close a form and return to the main workflow in Workflow Designer, click Start in the breadcrumbs or press Ctrl + Alt + Home.

Use the breadcrumbs to return to the main workflow

© 2019 Latitude Geographics Group Ltd. All Rights Reserved.

Documentation Version 5.10