Forms

Introduction

Forms can be used to quickly build a UI on top of your ruleset or for your workspace. A form can be simple, like a single page with a few inputs to execute a ruleset, or complex, like a multi-page form with data sources, subforms, and conditional visibility.

Form structure

A form has the following structure:

• Pages

  • Sections

    • Elements

• Subforms

  • Sections

    • Elements

• Data sources

• Translations

• CSS

Pages

A form can have multiple pages. Each page can have multiple sections. Each section can have multiple elements. In most cases it suffices to have a single section per page, but you can have multiple sections if you want to group elements together.

Subforms

A subform is identical in structure to a page, but it is meant to be used as a reusable component. You can add a subform to a page by adding a 'Subform' or a 'Table' element. Subforms can be used to create complex forms with repeating elements, like a list of items with multiple fields.

Sections

Present in both pages and subforms, sections are used to group elements together. You can use sections to group elements together visually, or to show/hide them based on conditions. Sections have an 'advanced settings' that can be expanded to show more options:

• Show labels: Show or hide the labels of the elements in the section

• Show input: Show or hide the input fields of the elements in the section

• Width: The width of the section, can be 'Full', 'Half', 'Third', 'TwoThirds', 'Quarter', 'ThreeQuarters', or 'Remaining'

  • This can be used to display two or more sections next to each other, for instance if two adjacent sections are both 'Half' wide, they will be displayed next to each other

• Alignment: The alignment of the elements within the section, can be 'Left', 'Center', 'Right', or 'Inherit'

  • This can be used to align the elements within the section, for instance if you want a button to be on the right side of the screen, you can set the alignment of the section to 'Right'

• Conditional visibility: Show or hide the section based on the value of a field

Elements

Elements are the building blocks of a form and are very diverse. These are the available element types:

• Input: A form input field

  • Text: A single line text input

  • Text area: A multi-line text input

  • Number: A number input

  • Currency: A numeric input, but has a currency symbol prefix

  • Percentage: Similar to number and currency, but with a % suffix

  • Date: A date input

  • Time: A time input

  • DateTime: A date and time input

  • Checkbox: A checkbox input

  • Radio: A radio button input - supports multiple options

  • Select: A dropdown input - supports multiple options

  • Button group: A group of buttons - supports multiple options

  • Color: A color input

  • Range: A slider input

  • Email: An email input field

  • Phone: A phone-number input

  • Password: A password field, with hidden input

  • Hidden: An invisible input, can be used to set a value on the form via its default value

• Subform: An element that renders a given Subform

• Output: A form output field. Is rendered as a disabled input field and supports the same input types as the input element

• Divider: A horizontal line to divide sections

• Button: A button that can be clicked

• Alert: A colored box with text, can be used to show custom messages, but can also be bound to a ruleset's single alert or all allerts

• Header: A header element

• Text: A text element, this is a WYSIWYG editor

• Table: A table element, can be used to display a list of items from various sources

• Video: A video element, can be used to display a video from YouTube or Vimeo

• Template: An element that supports raw HTML and Vue template markup (v-if, v-for, @click, etc.)

• Chart: An element that renders a chart based on static or dynamic data (uses Google Charts)

Some common properties of elements are:

• Label: The label of the element, this is the text that is displayed next to the input field

  • Does not apply to: Divider, Alert, Video, Template, Table, Chart

• Source: The source of the element, can be 'Ruleset' or 'Data source'. Only visible if there are any data sources defined in the form.

  • Ruleset: The element is bound to a field in the ruleset

  • Data source: The element is bound to a data source

• Property binding: The property binding of the element

  • Path mode: Can be 'Auto' or 'Manual'

    • When set to Auto, the Path is a dropdown that shows all available fields in the ruleset

    • When set to Manual, the Path is a text field where you can manually enter the path

  • Auto path source: Only visible when Path mode is set to Auto, can be 'Ruleset', 'Entity', 'Task', or 'Workflow instance'

  • Direction: Only visible for bi-directional elements, can be 'In' or 'Out'. Its value determines what can be picked in the Path dropdown

• Path: The path to the field in the form model, this is used to bind the element to a field in the ruleset

  • Does not apply to: Divider, Button, Alert, Header, Text

• Required: Whether the input is required

• Help text: A text that is displayed below the input field

• Tooltip text: A text that is displayed when hovering over the (?) icon next to the label

• On change: Actions that are executed when the value of the element changes

  • Only applies to Input

• Visibility: Can be 'Always', 'Conditional', 'Conditional advanced', or 'Never'

• Conditional visibility: Show or hide the element based on the value of a field

• Conditional visibility advanced: Show or hide the element based on the value of multiple fields

• Custom CSS classes: add styling using your own custom-defined CSS classes or the built-in Bootstrap 4 CSS classes

Data sources

A form can have multiple data sources. A data source can be used to populate a dropdown, a table, or any other element that requires data. There are four types of data sources:

• Persisted entity: Persisted entities from the database. These are entities from persistent libraries that are marked with 'Allow persistency'.

• Workflow instance: Workflow instances from the database. These are instances of workflows that are currently running.

• Workflow task: Workflow tasks from the database.

Each data source has its own options, for instance, a persisted entity data source has options to filter the entities, sort them, and limit the number of entities that are returned.

Translations

A form can have translations for multiple cultures. Each translation has a culture and a list of items. Each item has a key and a value. The key is the identifier of the translation, and the value is the translated text. This can be managed in a matrix view, where you can see all translations for all cultures at once.

For instance, when you have a form with an element with a Label 'First input', you can create a translation for the Dutch culture with the key 'First input' and the value 'Eerste invoer'. The value for the English culture can be left blank, as the default value is 'First input'. Another approach is to use more generic keys as Labels like 'FIRST_INPUT' and using that as the key in the translation.

CSS

A form can have custom CSS. This CSS is applied to the form when it is rendered. This can be used to style the form, for instance, to change the color of the buttons, or to change the font of the text elements.

If an element has a name, in the rendered form, the HTML-element will have a class with the name of the form element in the format fp-element-name-[name]. This can be used to style the element with CSS using a class selector. Note that when the name contains spaces or other special characters, these are replaced with a dash -.

The root HTML-element of a form has the class fp. Every form element has the class fp-element-type-[type].

Custom CSS

It is also possible to define custom CSS classes. That way, you can add your custom-defined CSS classes. It is also possible to use the built-in Bootstrap 4 CSS classes. Custom CSS classes are available on:

• Pages

• Sections

• Sub Forms

• Form elements

• Table columns