Form Controls

Article • 05.01.2021 • 16 minute(s) to read

Forms are the user interface of Form Activities and allow Users to interact with a Process. Thus, Forms are used in all Processes that require human interactions. Each Form is composed of various Form Controls. While the Form itself is merely the container, Form Controls like Texts, Buttons, Checkboxes, etc. allow users to interact with a Process and its data.

Form Designer

The Form Designer allows you to create and modify Forms. The Form Designer is accessible via the Edit button of the Form design and action setting of any Form Activity.

Sections of the From Designer

The menu offers several functions to design the Form and its Actions:

  • Debug process - Creates a Debugging Instance of the Process this Form is in and switches directly to it.
  • There are several ways to filter for particular Form Controls on the Form. All of these can be applied in an arbitrary combination:
    • Filter by label or id/name - When you start typing in this field, only Form Controls with a matching Id / Name are shown.
    • Control type - Limits the shown Form Controls to the specific type of Form Controls. The setting Control type shows all Form Controls, i.e., does not do any filtering.
    • - Hides or shows all disabled Form Controls.
    • - Hides or shows all Form Controls with a condition.
    • - Hides or shows all hidden Form Controls.
    • Generate from entity type - This button opens the Generate form from entity type menu in the Settings section on the right. The Generate form from entity type menu allows you to automatically generate a Form based on an Entity Type definition:
    • Clear - Removes all Form Controls from the current Form.
Form Controls
This section lists all available Form Controls grouped in the three categories BASIC, ADVANCED, MISC and CUSTOM. CUSTOM is empty if there have been no Custom Form Controls defined so far.
Form & Action Design

In the middle section you see all Form Controls and Actions placed in the Form. The upper part shows all Form Controls fulfilling the current filter setting. New Form Controls can be added by dragging them from the Form Controls section on the left into this upper part.

The lower part shows dedicated Actions Buttons. New dedicated Actions Buttons can be added by pressing Add Action. Each dedicated Actions Button is shown along with some information about it:

  • - Delete an Action
  • Preview - Shows how the Button looks like on the final Form.
  • Action - Action triggered by this Button
  • Outcome - The Outcome used to leave the Form Activity when this Action is triggered.
  • - Opens the properties of the Action in the Properties section on the right.
  • - Modify the order of the Actions
Properties
This section shows the properties of the currently selected Form Control or Action. The properties of Generate from entity type are also shown here.
Close
Saves all modifications and closes the Form Designer.

Actions

Actions finish the interaction with a Form. When an Action is triggered by a User, the Instance will leave the Form Activity by the specified Outcomes and proceed to the next Activity of the Process. Various Form Controls can trigger Actions:

  • The dedicated Action Buttons shown in the lower part of the Form & Action Design section are the main way to present Actions to the Users. Since these are always placed on the lower part of any Form it is easy for the Users to identify them.
  • Buttons placed amid other Form Controls can also trigger Actions and are functionally identical to the dedicated Action Buttons. Their placement needs to be done with care, so that users can identify them and interact swiftly with the Form design.
  • Texts can trigger actions when configured to do so. The Action is triggered by Users pressing the Enter key while the cursor is in the Text.
Action properties

The Action properties are shown in the Properties section on the left. Not all properties presented here are available in any case, since Buttons and Texts obviously differ in their representation:

  • Label - Name on the Button representing the Action
  • Outcome - When the Action is triggered the Outcome selected here is used to leave the Form Activity. If multiple Outcomes with the same name exist, all of them are used and the execution of the Instance continuous in parallel.
  • Action - Specifies the triggered Action type:
    • Discard - Discards all modifications of the Form Controls.
    • Save - Stores the data from the Form Controls in the Variable backing the Form Activity. The Variable is set in the Variable configuration of the Form Activity.
    • Sign - Stores only the signature in the specified Attribute.
    • Sign and Save - This is a combination of Sign and Save. It stores the signature in the specified Attribute and stores data from the Form Controls in the Variable backing the Form Activity.
  • Style - Only available, if the Action is linked to a Button. Then, this property sets the color of the Button representing the Action.
  • User attribute - Specifies in which Attribute the Id of the User triggering the Action will be stored. The Attribute has to be selected from the Variable backing the From. The Attribute needs to be of type Big Integer if only one User can complete the From or has to be an array of Big Integer, if the property Must all owners complete the task? is set for this Action and all owners are required to complete the Form.
  • User group permissions - Only Users in the User Groups specified here can trigger the Action. All Users not in the specified User Groups will not see the Button. If no User Groups are specified, all Users in any User Groups will see and can trigger the Action. User Groups can be added by pressing Add user groups and removed by pressing .
  • Return to dashboard? - When set to Yes, the User will be send back to the main Dashboard by this Action regardless if there are any further Forms to show or not. When set to No, the User will be presented with the next Form. When there are no further Forms left in the Instance, the User will be send back to the main Dashboard in any case.
  • Skip form validations? - When set to Yes, any validation rules configured at the Form Controls are ignored. This might be desirable for Discard Actions. When set to No, all validation rules configured at the Form Controls are enforced.
  • Claims ownership of task? - When set to Yes, only the User triggering the Action will remain the owner of the From and all other Users or User Groups will be relieved of their owner status. When set to No, the owner configuration is unmodified.
  • Must all owners complete the task? - Specifies if one owner can trigger the leaving of the Form by this Action (No) or if all owners have to individually trigger this Action (Yes) to leave the Form and continue the Instance. When set to Yes, the following logic applies:
    • All Users set individually by their Id as owners have to trigger the Action separately
    • One User per configured User Group has to trigger the Action
    • The triggering of the Action by Users who are in more than one User Group is counted for all User Groups simultaneously. I.e., it is not necessary for Users to trigger the Action multiple times if they are part of more than one User Groups configured as owners.
    • When Must all owners complete the task? is set to Yes, special care must be giving in the configuration of the other Actions:
      • Only one Action of a From is allowed to be set to Yes. Otherwise, deadlocks are created when individual Users choose different Actions.
      • Usually only read-only Forms require the completion by multiple owners. If the Form is not read-only, one User can complete it, then another use can modify it without the first User noticing it. However, comment fields are often an exception to this read-only rule.
      • The Attributes configured at Signature attribute and User attribute have to be arrays.
  • Reset approval of all owners - Triggering this Action resets other Actions (Yes) or leaves other Actions unchanged (No) when the Form Activity is entered again in the same Instance. This property is particular important, when Must all owners complete the task? is used:
    • In the case that some, but not all of the Owners, trigger an Action which has Must all owners complete the task? set to Yes and the remaining Owners trigger another Actions, the Instance leaves the Form Activity and continues the execution of the Instance.
    • If this continuation leads the Instance back to the same Form Activity, the Novunex Platform still remembers that some Owners already triggered the Action which has Must all owners complete the task? set to Yes.
    • If this is not desired, Reset approval of all owners needs to be set to Yes, so that the Novunex Platform resets all previously triggered Actions, when a From Activity is re-entered in the same Instance.
  • Show comment field - Shows (Yes) or hides (No) a comment field. When the filed is shown, the Users can write a free-text comment in it.
  • Signature attribute - This property is only available for Sign and Sign and Save Actions and sets in which Attribute of the Variable backing the Form the Signature is stored. The Attribute needs to be of type Signature if only one User can complete the From. It has to be an array of Signature, if the property Must all owners complete the task? is set to Yes and all Owners are required to complete the Form.
  • Require confirmation? - If set to Yes, the Users will be presented with an additional confirmation dialog when they trigger the Action. The dialog will present the message entered in the Confirmation message field that appears when you set Require confirmation? to Yes. If set to No, no confirmation dialog is shown to the Users and the field Confirmation message is also not shown.

Form Control Expression

Form Control Expressions are used to evaluate conditions based on the values entered by Users into Form Controls. Form Control Expressions are executed in the Browser and should therefore be kept short and simple to ensure a fast response of the Form they are part of.

The Expression Editor allows you to enter a Form Control and shows a Quick Reference on available functions and parameters.

Expression Editor

The Expression Editor allows you to enter a Form Control and shows a Quick Reference on available functions and parameters.

Basic Syntax

Form Control Expressions are evaluated by the JavaScript engine of the Browser shown the From. Hence, their Syntax is closely related to JavaScript.

Literals
  • Boolean - true and false
  • Numerical:
    • 12 - Number without decimals
    • 9.87, .87, 9.87e4, 9e4, 9e+4, 9e-4, .9e-4 - Decimal numbers
  • String - String literals are enclosed in quotes, e.g., "Hello String"
  • Time and Dates - The time and dates are handles by Momentum.js and parsed in ISO 8601 format. If this fails, the RFC 2822 format is tried. If this also fails, the time and date is not recognized.
Arithmetic and Logical Operators

Operators allowing you to do basic calculations and evaluate logical expressions:

  • Logical Operators:
    • == - Compares for equality
    • === - Strict comparison for equality
    • !=- Compares for inequality
    • !== - Strict comparison for inequality
    • ! - Logical NOT
    • && - Logical AND
    • || - Logical OR
    • < - Smaller
    • <= - Smaller or equal
    • > - Greater
    • >= - Grater or equal
  • Mathematical Operators:
    • + - Addition
    • - - Subtraction
    • * - Multiplication
    • ** - Exponentiation
    • / - Division
    • % - Modulo, i.e., remainder of a division
  • Member Access with . and [...], respectively

The round brackets ( and ) can be used to groups and thus prioritize of expressions. The operators have the following priority, ordered by highest to lowest:

  • Grouping by brackets ( and )
  • Member access ., [...] and function call with (...) with left-to-right Associativity
  • Logical Not ! with right-to-left Associativity
  • Exponentiation ** with right-to-left Associativity
  • Multiplicative *, /, % with left-to-right Associativity
  • Additive -, + with left-to-right Associativity
  • Relational inequality <, <=, >, >= with left-to-right Associativity
  • Relational equality ==, !=, ===, !== with left-to-right Associativity
  • Logical AND && with left-to-right Associativity
  • Logical OR || with left-to-right Associativity
Form Controls and Variable Access

The values of Form Controls can be access by a Dollar sign $ and their name enclosed in square brackets []:

  • $[FormControlName] - Access value of Form Control with Id / Name FormControlName
  • $[FormControlName][n] - Access value on position n of the Form Control array with the Id / Name FormControlName
  • _index - Current row in an Grid. Hence, $[GridName.ColumnName][_index] accesses a Form Control in a Gird from another Form Control from the same row. I.e., _index will be automatically replaced with a current row. Be aware that _index is only defined for Form Controls in the same Grid.

The values of Entity and Context Variables and their attributes are accessed by a pound sign # and their name enclosed in square brackets []:

  • #[MyEntityVariable.Attribute] - Access the value in an Attribute of an Entity Variable
  • #[MyContextVariable] - Access the value in a Context Variable with no attributes
  • #[MyContextVariable.Attribute] - Access the value in an Attribute of a Context Variable
Special characters

When working with Strings, you might need to escape characters or use special control characters:

  • \\ - Escape character
  • \n - Line feed
  • \r - Carriage return
  • \t - Tab

Functions & Methods

Here you find a list of commonly used functions or methods in Form Control Expression.

Date and Time

Methods for working with date and time values:

  • moment( $[FormControl] ).format( formatString ) - Format time in FormControl according to formatString. The available formatting strings can be found on Moment.js Display Options.
  • moment( $[FormControl] ).fromNow() - Outputs a human readable version of the time difference between now and the time in FormControl. Examples of the output format are A few seconds ago or A month ago.
  • moment( $[FormControl] ).add( duration, unit ) - Returns the time in FormControl plus duration in unit. The available units can be found at Moment.js
  • moment( $[FormControl] ).subtract( duration, unit ) - Returns the time in FormControl minus duration in unit. The available units can be found at Moment.js
  • moment( $[FormControl] ).isBefore( $[OtherFormControl] ) - Checks if the time in FormControl is before the time OtherFormControl
  • moment( $[FormControl] ).isSameOrBefore( $[OtherFormControl] ) - Checks if the time in FormControl is before or equal to the time OtherFormControl
  • moment( $[FormControl] ).isAfter( $[OtherFormControl] ) - Checks if the time in FormControl is after the time OtherFormControl
  • moment( $[FormControl] ).isSameOrAfter( $[OtherFormControl] ) - Checks if the time in FormControl is after or equal to the time OtherFormControl
  • moment( $[FormControl] )isBetween( $[SecondFormControl], $[ThirdFormControl] ) - Checks if the time in FormControl is between the time in SecondFormControl and ThirdFormControl
Type Conversion

Functions and methods to convert between various data types:

  • parseInt(string) - Converts string to an integer, string can be a literal like "123" or referencing a Form Control like $[FormControl]
  • parseFloat(string) - Converts string to an decimal number, string can be a literal like "12.34" or referencing a Form Control like $[FormControl]
  • numericResult.toString() - Converts the integer or decimal number in numericResult into a string.
String handling

Functions, methods and operators to manipulate and work with strings. The strings can be a literal like "Hello" or referencing a Form Control like $[FormControl]:

  • + - String concatenation, e.g., "The amount is " + $[FormControl] + " Euros"
  • string.toLowerCase() - Convert string to lower case
  • string.toUpperCase() - Convert string to upper case
  • string.substring(n, m) - Retrieves the part of string starting at n (inclusive) and ending at m (exclusive).
  • string.indexOf(otherString) - Returns the first staring index of otherString in string and -1 if otherString was not found in string. Hence, string.indexOf(otherString) >= 0 can be used to check if otherString is part of string.
Conditional
The conditional condition ? trueStatement : falseStatement is used to return different values based on a condition. The example $[FormControl] == 1 ? "It is 1" : "It is not 1" will return the string It is 1 if FormControl holds the value 1 and It is not 1 otherwise.

Form Controls

Form Controls like Texts, Dropdowns, Checkboxes etc. allow Users to enter, view and manipulate data. There are two types of Form Controls:

  • Predefined Form Controls come ready to use, meaning that you can put them on Forms right away.
  • Custom Form Controls allow you to define new Form Controls with special functions not covered by the Predefined Form Controls.

Custom Form Controls

The Novunex Platform offers you the possibility to create Custom Form Controls allowing you to design and implement application-specific User interaction functionality.

In the majority of all Processes and Application the Predefined Form Controls will be suffice. In these cases, there is no need to create Custom Form Controls. Custom Form Controls are only required when you do not find the functionality you are looking for in the Predefined Form Controls.
HTML of the Predefined Form Controls is somewhat of an intermediate type allowing you to use HTML and JavaScript to create a customized Form Control without the effort required by the Custom Form Controls.

Custom Form Control List

All Custom Form Controls available in a Subscription are listed in the Form Control section of the Subscription Menu. It offers the following interactions:

  • Menu - Main interaction controls:
    • The search bar lets you search for Custom Form Controls
    • Install from package - Installs a Custom Form Control that was exported earlier. The export option is available as Pack in the List of Custom Form Controls.
    • Create new control - Changes to the Form Control Editor where you can create a new Custom Form Control
  • List of Custom Form Controls - Here you find all Custom Form Controls that mach your search. If you did not execute a search all Custom Form Controls are show here with these information and interactions:
    • ID - Unique identifier of the Custom Form Control
    • Icon of the Custom Form Control - Visual representation of the Custom Form Control
    • Name of the Custom Form Control - You can click the name of the Custom Form Control to open it in the Form Control Editor
    • VERSION - Version counter showing how many times the Custom Form Control has been edited
    • CREATED - Shows when the Custom Form Control was first created.
    • MODIFIED - Shows when the Custom Form Control was last modified.
    • - Opens a context menu to interact with the Custom Form Control:
      • Pack- Exports the Custom Form Control into a file, so that it can be imported by the Install from package option of another Subscription.
      • Edit - Opens the Custom Form Control in the Form Control Editor.
      • Delete - Delete the Custom Form Control.
  • Pagination - Sets how many Custom Form Controls are shown at once.

Sections of the Custom Form Control overview

Form Control Editor

The Form Control Editor lets you create a new Custom Form Control or edit an existing one.

Sections of the Form Control Editor

Menu

The Menu allows you to finish the work on by:

  • Cancel - Discard all changes
  • Save & close - Save all changes
  • - Pressing this icon also opens:
    • Save - Save current changes
    • Save as… - Save under a new name
General Settings

The general setting specify how a Custom Form Control is identified and used:

  • Icon - Visual representation of the Custom Form Control
  • Name - Name of the Custom Form Control identifying it towards the Users
  • Can be used in grid? - Specifies if the Custom Form Control can be embedded in a Grid (Yes) or not (No).
  • Type - Unique name of the Custom Form Control identifying it internally in the Novunex Platform. The Type has to be unique for the Subscription
  • Component name - Automatically generated from by combining Type with a prefix. The Component name is required to work with the Custom Form Control in HTML and JavaScript code.

Predefined Form Controls

This table list all available Predefined Form Controls.

Icon Name Description
Text The Text or Text field allows Users to interact with short texts. [Learn more]
Dropdown Dropdowns allow Users to select one value from a predefined list of options. [Learn more]
Text Area The Text Area is intended to be used for long texts. [Learn more]
Number Numbers are input fields for integer or decimal numbers. [Learn more]
Multi Select Multiselect presents a list of predefined values and the Users can select values by clicking them. [Learn more]
Password Password is similar to Text, but hides the characters the User typed. [Learn more]
Checkbox Checkboxes present one or more options, where the Users can select and un-select each of them separately. [Learn more]
Radio Radio presets options to the User so that only one option can be selected at the same time. [Learn more]
Switch Switches are used when Users have to interact with fixed options. [Learn more]
Buttons Buttons trigger Actions when they are pressed. [Learn more]
Lookup Lookup load and show the first Entity of a given Entity Type that match the filter rules. [Learn more]
Explorer Select The Explorer Select provides a configurable view of the Entities of a given Entity Type. [Learn more]
Date Time [Learn more]
File The File Form Control allows the Users to upload files on the Novunex platform. [Learn more]
Text Editor The Text Editor is designed to format and edit of text. [Learn more]
Expression Expressions are used to calculates values or compose strings with Form Control Expressions. [Learn more]
Grid Girds are special Form Controls implementing a container for other Form Controls. [Learn more]
Data Explorer The Data Explorer enables Users to browse though Entities of a specific Entity Type. [Learn more]
Report Viewer The Report Viewer enables Users to browse though the results of a Data Query. [Learn more]
Data Viewer The Data Viewer displays the Attributes of a single Entity. [Learn more]
HTML HTML allows you to use HTML and JavaScript directly to create your Form Control. [Learn more]
Timeout Timeouts trigger an Action once the configured duration has elapsed. [Learn more]
Title Title shows a string on the Form that is formatted as a title. [Learn more]
Read Only Read Onlys displays one Attribute but do not provide any way to modify it. [Learn more]
Hyperlink Hyperlink displays clickable links to other Forms, Dashboards or web pages. [Learn more]
Image Image displays pictures in common formats that browsers can render like PNG, JPG, etc. [Learn more]
Columns Columns offer no interactions to the Users but are a container to place more then one other Form Controls in a row. [Learn more]