Form Config & Layout (View)
- 1 What is the Form Config?
- 2 Configuration Attributes
- 2.1 title
- 2.2 description
- 2.3 icon
- 2.4 color
- 2.5 hidden
- 2.6 permissions
- 2.7 schema
- 2.8 output
- 2.9 input
- 2.10 forwardOnSuccess
- 2.11 onSuccess
- 2.12 layout
- 2.12.1 Vertical orientation
- 2.12.2 Horizontal orientation
- 2.12.3 Nesting layouts and orientations
- 2.13 field
- 2.14 Grouping with title and border
- 2.15 type
- 3 Internationalization (i18n)
- 4 Special Form Types
- 5 Variable substitution
What is the Form Config?
The Form Config is the central configuration file of a form. It defines things like:
How the fields of a form must be positioned in the view (= the view / layout).
Where to load and write the form model from / to.
Where to load the schema of the form from.
What to do, after a form has been submitted.
Title, description, type and other settings of the form.
Here is an example of how such a form config could look like:
{
"title": "Add person",
"description": "Add a new person",
"hidden": false,
"schema": "$uri:property:global/app/tld.domain.myapp/object/person/v1/schema",
"input":"$uri:property:global/app/tld.domain.myapp/object/person/v1/instance/67b07f3c-e006-4bec-a790-ef25b9fe97df",
"output": "global/app/tld.domain.myapp/object/person/v1/instance/${vars.property.uuid}",
"layout": {
"orientation": "vertical",
"items": [
{
"orientation": "horizontal",
"items": [
{
"field": "firstName"
},
{
"field": "lastName"
}]
},
{
"field": "age"
},
{
"field": "gender"
},
{
"field": "birthDate"
}
]
}
}
The form config must be stored in the property store inside the form
subfolder of your app. For example:
global/app/tld.domain.myapp/form/person
All form configs inside the form folder will be automatically picked up and shown in the forms overview of an app. For example, here you can see the form Add person
automatically listed:
Configuration Attributes
The form config contains different attributes in order to specify the form. All of these attributes are described in detail below.
title
The title
defines the title of the form to be displayed in the web ui and in other locations.
This can be a static text or an i18n uri like $uri:i18n:myTitle
for example.
description
The description
is optional and describes the intention of the form.
This can be a static text or an i18n uri like $uri:i18n:myDescription
for example.
icon
Each form can have an individual icon. This value must be a code name from the Google Material Icons as listed here: https://fonts.google.com/icons
This value is optional. If not given, the icon with code name ballot
is shown as default:
color
The color of the form icon is used. If not specified, the secondary color is used, which depends on the style settings. By default this is a blue color like this:
The color value can be a hexadecimal value, like this:"color": "#FFA500"
Or it can be a constant selected from the Colors palette.
For example you could use the color palette constant “green” like this:"color": "green"
Another example:
"color": "red-8"
hidden
This optional attribute defines whether the form should be shown as tile inside the app ("hidden": false
) or not ("hidden": true
).
The form can be still loaded by its URL if required and used embedded in lists or workflows.
If this attribute is missing, "hidden": false
is used as a default.
permissions
By default any logged-in user can see the the form using role based access rules (RBAC):
RBAC-A: Is member of
ROLE_DEVELOPER
orRBAC-B: Is member of
CAN_APP_<app.name>
of the according app andROLE_USER
.
This is the default in case no permissions
attribute is defined in the app config. This default can be overwritten by specifying the permissions
attribute in the form config. In this case the RBAC-B will be ignored. Instead RBAC-C applies:
RBAC-C: User is member of
CAN_APP_<app.name>
and at least one of the given permission rules is valid.
Example:
{
...
"permissions": {
"read": ["ROLE_GUEST"]
}
}
The attribute read
defines a list of permission strings the currently logged-in user must match at least one of. By default such a permission string is the name of a required role. In this example, any logged-in user assigned to ROLE_GUEST
and CAN_APP_<app.name>
is able to see this form. In case the user is assigned to ROLE_DEVELOPER
he can also see this form since this will always apply.
PIPEFORCE URIs as permissions
SINCE version 10
Furthermore, also PIPEFORCE URI prefixes are supported to define permissions
such as:
$uri:group:<groupname> = Logged-in user must be member of group with name <groupname>.
$uri:role:<rolename> = Logged-in user must have assigned this role (this is used by default also if no such prefix is used.)
Example:
schema
The schema
attribute defines a PIPEFORCE URI which is called in order to retrieve the Form schema for this form.
For example, the attribute could look like this:
Which could return a JSON schema like this:
output
The output
defines the path in the property store where the form data must be stored as JSON property after the form has been submitted. Example:
Since path ends in a slash / the form framework identifies this as a new property creation and automatically appends the uuid of the new property as “filename” at the end of the path (since version 10). In versions < 10, you had to add the PE ${vars.property.uuid}
at the end. This PE will be interpreted on the server side and replaced by the UUID of the property. This approach is deprecated and will be removed soon.
The form handling pipeline can listen to a property.created
event on this path then in order to get informed when a new property was created on this path:
The same way it works with property.updated
event.
Also see:
input
The input
attribute defines a PIPEFORCE URI which is called to retrieve the initial input data for the form in order to set predefined values on the form widgets. For example, the input parameter could look like this in order to load a JSON property from the property store:
Which could return a form data (= model) as JSON to be edited similar to this:
forwardOnSuccess
Deprecated Use onSuccess
instead.
This attribute defines an URL, or a path relative to the portal in order to forward to after the form has been submitted successfully. In case the submit caused an error, the form will stay at current location in order to display the error. In case this attribute is not given, the form will show the default submit success message.
onSuccess
Since 9.0
This defines what should happen in case the form was successfully submitted. This is optional. If not defined, the default success message and icon will be shown:
forward
Forwards to a URL or a path relative to the portal. In case the submit caused an error, the form will stay at current location in order to display the error:
action
- must be set toforward
.url
- The URL or the path relative to the portal where to forward after success.
message
Shows a text message and an icon in case the form was successfully submitted.
action
- Must be set tomessage
.text
- Can contain a static text or an i18n key. If not given, the default text will be shown.
See: TODOicon
- Must be a code name from the Google Material Icon. If not given, the default icon will be shown. See: https://fonts.google.com/icons .color
- Defines the color of the icon. If not given, the default icon color will be shown.
See Colors .
layout
By default, in a form, all widgets (= fields) of the Form Schema are displayed vertically, each ints own row.
Vertical orientation
You can change this default by configuring orientation
of the layout in the Form Config.
To do so, firstly you need to add the element layout
to the form configuration as shown in this example:
This example layout configuration would create exactly the default layout again:
Horizontal orientation
You can then change the orientation
, width
and height
of a layout item like this:
The attributes width
and height
can be also specified on individual widget fields.
This would result in this form layout afterwards, where all fields are displayed in a single row (horizontally):
Width of 900 in horizontal layout item prevents fields to cover all of the available space.
In horizontal orientation, layout items and fields, by default, attempt to use maximum width while considering neighboring fields, making them responsive.
Both min-width
and max-width
can be also used in place of width
to reach responsiveness within defined limits.
Nesting layouts and orientations
Layouts and its orientations can be nested in order to create quite complex form structures. Here’s an example:
This example would produce a form with nested orientations like the one shown below:
field
Inside a layout element you can place field elements pointing to field ids (widgets). This element can contain additional attributes like these:
hidden
If set to true, the widget is not shown in the form, but the value from the input is sent to the backend on submit. Example:
readonly
If set to true, the widget value cannot be changed. Example:
Grouping with title
and border
If "border": true
, a border is drawn around the current layout element.
If attribute title
contains any value this is set as title of a group of the current layout element.
You will usually use both together to create a group of fields. Example:
This will produce a grouping with title like this:
type
TODO
Internationalization (i18n)
The title and description of a form and also its validation messages can be internationalized (= translated to different languages). See here for more details, how this works: Internationalization (i18n).
Special Form Types
Document Understand Form (with AI support)
TODO
Variable substitution
Request parameters
It is possible to use request parameters in the form config attributes as placeholders, like this:
In order to set the taskId dynamically, one could call the form like this:
After the placeholder has been replaced, the input parameter will look like this:
These attributes in the form config support request parameter variable substitution:
input
output
schema
Property attributes (PEL)
It is also possible to specify a PEL inside some of the config attributes. This way the PEL will be executed at server side and the result will be used to form the final config value. For example:
In this example the PEL ${property.uuid}
will be resolved to the UUID of the property which is about to be created when sending this output.