Important: The ui module with forms implementation makes use of the Vaadin and Vaadin Charts frameworks. Make sure to purchase the Vaadin Charts license if you are designing charts. The users of your Application User Interface and Management Console, do not require any additional licenses.

A form defines the content displayed in the front-end application. It can be displayed either by a document or by a to-do:

When displayed by a document, the form is used as content of a page that is permanently available to the user.

Form with a table in a document
When displayed by a User Task in a to-do, the form is used as the content of the to-do which is part of a process instance and disappears once the user submits it.

Rendered to-do with the form
The form comprises a tree of form components, such as, input fields, radio lists, etc. Each component produces events whenever something happens. These events can be caught by listeners. When a listener catches its event, the event is queued and processed in the event-processing cycle. The way the event is processed is defined by the listener.

For example, if the user clicks a button, the button fires an event, called ActionEvent. The event is caught by the ActionListener attached to the button component. The listener defines what the event causes, so the event can refresh form components, persisting the data, submitting the to-do or document, etc.

When the user opens a to-do or document, the following happens:

The system creates an context level, called screen context.
The system creates copies of the data from the model context in the screen context.
The system initializes form local variables and builds the form.
The form tree is rendered as web content and populated with the data from the screen context.

This allows you to change data in the form without instantly influencing the data in the "real" base context.

A form can take input parameters and define its local variables.

You can create also custom components and add them to the form-editor palette. For further instructions, refer to the Software Development Kit Guide.

Form Editor with a Custom Submit Button

Form Execution Levels

A model instance state is defined by its properties and data in its contexts. When the model instance creates a form, the context hierarchy is created on another execution level to isolate the form data. As a result, the changes of such form data are applied only on the "real" data only when explicitly required: to-dos or documents with a ui form are created on their own level that overlays the model instance level.

So while model instances exist on the base context level, when a model instance hits a user task or when a document of model instance is created, the system creates a new level for the form of the document or task. This context level is a copy of the base context level and is referred to as the screen context level: When the user changes the data in the form, the changes are performed on the context of the screen level.

Schema with execution levels of a model instance, and a to-do and form

Note that sublevels always hold only the differences to the context hierarchy in the superlevel.

To apply the changes, the user must merge the screen level into the base level: this happens when the form is persisted. Persisting is performed as part of event processing: hence, to merge the screen level into the base level, you need to create a listener with the persist or submit action.

If you need to create another execution level over the screen level to isolate data within your form, you can do so with a View Model component: the component creates another execution level referred to as an evaluation level.

Continue to: