Please rate how useful you found this document: 
Average: 2.8 (4 votes)

Overview

Final users interact with a form through the controls available within it. The controls of the HTML5 responsive Dynaform designer use global variables created within the project to interact with elements of the project when the data needed must be entered by a user through a form. ProcessMaker has created an interface that allows users define these variables, add options and define the data type.

General Controls

When a new form is created, the container where all controls will be added (form) and the container where each particular control will be added as well (row) have their own particular functionality and properties inside them.

Web Controls

The responsive Dynaform designer comes with the following controls that are directly related to the variables created in the project:

The following controls that were available in previous versions of ProcessMaker are not available inside version 3:

If needing to manage the controls above, take into account that the properties of the new controls replace the functionality to most of them by simply configuring the behavior of the controls.

Other Controls

These controls are available inside the designer and give more functionality to forms such as managing documents, links, images, adding extra HTML code, etc. These controls are not directly related to a variable of the project. These controls are directly added into the design and each one of them can be configured using its properties. The available controls of this section are:

* From version 3.0.1 this control changed its name from "Comment" to "Label".

Management of Variables Inside Forms

Take into account the following considerations when working with variables related to controls inside the Dynaform designer.

Allowed Variables for each Control

Each of the controls available has different properties that give the control major functionality and allows users to define the scope of the control. The explanation of these properties and their characteristics are in the following sections. The table below details the available controls for each data type:

Control/Data Type String Integer Float Boolean Datetime Grid Array File ** Multiple File
Text
X
X
X
TextArea
X
X
X
Dropdown
X
X
X
X
Checkbox *
X
Checkgroup *
X
Radio (group)
X
X
X
X
Suggest
X
X
X
X
Datetime
X
Hidden
X
X
X
X
Grid
X
File
X
Multiple File Uploader
X

*Available Version: From version 3.0.1.4, checkboxes controls have been divided into two: "Checkboxes" and "Checkgroups". Take a look at their documentation to learn more about it.

**Available Version: From version 3.0.1.5.

Null Value

The following are the conditions used for working with null values in Dynaforms

  • Fields of Dynaforms related to variables have a null value initially (the null value is interpreted as "missing value").

  • If the field (rendered) is not altered by the user in a Dynaform at any moment, the value will continue to be null.

  • An empty string is different to the null value. If the user cleans the content of a field, the empty string is used as a valid value (it means that the value saved will be the empty string).

  • Take into account that variables store null values, thus Report Tables and PM Tables fields must also support null values

Default Value

The following are the conditions used for working with default values in Dynaforms

  • The default value in a field of a Dynaform is set as the value retrieved from the field (when it is rendered) if it doesn’t contain any previous value.
  • The default value is set as the value retrieved from the field only if its value is null (not the value set by the user even if that value is an empty string).
  • The default value overrides the "SQL" and "Options" properties. This is the order in which the values are saved (shown by priority):
    • First SQL value //minor priority
    • First Option value
    • Default Value //max priority
  • If the default value is defined, it overrides the options or SQL values. If the default value is not set, the first value in the Options property overrides the value set by SQL.

      • Default Value in Fields with Domain Values

      The default value must be defined inside the domain of values retrieved by the SQL query or set in the Options of the variable of the field. The following are the fields in which this consideration must be taken into account:

      These fields will look for the value set as default in the data returned by the SQL query or by the Options set for the control. If the value is found in the data retrieved, then the default value is set as the value by default. If the default value is not found in these domains then, the default value is not saved in the data of the control.

      Default Value for Suggests

      In case of the suggest field, the behavior of the default value is different. The default value can be out of the domain defined in the domain (SQL and options). It’s not required that the default value be part of the domain.

      The default value will be displayed in the text area of the suggest control and stored in the variable. In that case the value and the text displayed are the same.

      Default Value in Single Value Fields

      In the other controls that do not define a domain of options, just set the default value in the properties of the control.

      Setting Multiple Default Values

      Checkgroups allow zero, one or multiple options to be selected by default. To select multiple options, separate the values of the selected options with vertical pipes ( | ) . Remember to use the values of the options, and not the labels, which is the text displayed to the user. For example, if wishing to select just Canada in a checkgroup of countries, then enter CA in the default value property. To select Bolivia, Argentina and the United States by default, then enter BO|AR|US in the default value property.

      Fields that Must Select an Initial Value

      The fields that define a domain of options define a group of possible values.

      Only the dropdown control always selects a value when it is first rendered. In order to define an empty or null value, create an option without value and add any description such as “--Select an option--”.

      Note: From version 3.0.1.5 the Placeholder property was added to this control in which it is possible set an empty value.

      If the dropdown is required and the value returned is null, then the validation will return false and it will not be possible to go to the next step. The form will ask to select a value from the dropdown.

      SQL Format

      The SQL property is used in many controls in the Dynaform. Take into account the following conditions to set the SQL instructions. For more information about the SQL property, see Dynaform Control Properties - SQL.

      SQL instruction that returns values and text

      The following rules must be applied to the controls:

      The following syntax must be used in the SQL property:

      SELECT [value Column], [text Column] FROM [table Name] WHERE [any condition]

      Where:

      • value Column: Is the identifier of the option.

        Note: Identifiers just support one-word text and characters as . and @. The following characters are not supported when they are between words: ', |. `,  (space), ", !, and ^ (by example: A^A). In addition, the ProcessMaker Dynaform Designer does not support SQL queries with the * identifier. Using the * identifier is considered a bad practice because generates performance issues.

      • text Column: Is the text that is displayed in the control.
      • table Name: The name of the table in the database.
      • condition: Any condition for the SQL query

      SQL instruction that returns a value

      The following rules must be applied to the controls:

      • Textbox
      • Textarea
      • Hidden

      The following syntax must be used in the SQL property:

      SELECT [value Column] FROM [table Name] WHERE [any condition]

      Where:

      • value Column: The value must always be the first field in the query. It is the identifier of the option.

        Note: The * identifier is not supported in SQL queries.

      • table Name: The name of the table in the database.
      • condition: Any condition for the SQL query.

      SQL and Options in Controls

      There are two groups of controls that use the SQL and Options properties in different way. Both of them are explained below

      SQL and Options that Define the Domain of Options

      The values returned by the SQL query and the Options properties constitute the domain values of the field. The valid values for the control are only the defined in the domain. The following controls can contain and use the SQL property and Options property as domain values:

      • Dropdown
      • Checkgroup
      • Radio group
      • Suggest

      Note: The * identifier is not supported in SQL queries.

      SQL Property in Scalar Controls

      The SQL property can also be used as a scalar value in a control. If there are more than one value as the result of the execution of the SQL query, only the first value is used to set the control value.

      The following controls can contain and use SQL property as scalar value:

      • TextBox
      • TextArea
      • Hidden

      Consider the rules defined in the section “Default value” in order to define which value is set when the SQL and Default Value are defined. Note that these controls do not have the property Options .

      Note: The * identifier is not supported in SQL queries.

      Fields without SQL and options properties

      The following fields don’t include the SQL and options properties:

      • Title
      • Subtitle
      • Label
      • Checkbox
      • Datetime
      • Link
      • Image
      • File
      • Multiple File Uploader
      • Submit
      • Button
      • Grid
      • Panel
      • Subform

      Duplicated Variables in Dynaforms

      Inside a Dynaform it is recommended to set only one instance of a variable. Nevertheless, it is possible to define two fields using the same variable in the following situations:

      • The same variable is assigned in two or more subforms in the design of the form (it means that the subforms added used the same variable in their controls). Remember that a form can only be used one time as a subform in a form, but a form can have more than one subform in its design.
      • The design of the subform is modified after the subform was assigned to many forms. And a variable is duplicated in any of the main forms.

      The designer wants to duplicate the use of the variable in two sections of the form, and display or hide one of the associated fields depending of the design. In that case, the Dynaform designer is going to alert the architect that a variable is being used in two or more fields, but the architect must define if the field with reference to the same variable is possible.

      When running cases, if a variable is used in two or more controls, then the control in which the value of the variable is set at the end will be saved as the value of the variable. The definition of the order of the controls is top to down and left to right (note that this depends on the browser). To avoid these problems it’s recommended to not duplicate variables.

      To know more about variables restrictions, see naming variables best practices.