Activiti Form viewer

The Activiti Form viewer is the component used to render forms related to the Activiti process engine, related to either starting new processes or completing manual tasks.

A few nice-to-know items about the Activiti Form viewer:

• The form object is created the first time it is rendered. On repeated renderings (after submits, etc), the same form object is reused, with all the information intact (even if information is not rendered every time).
• Form components are “bound” to a data model, where they get their values from and store their values to. However, until a form is submitted or saved, values in the form component are independent from values in the data models.

Overview

The figure below gives a quick overview of the models available to the Activiti FormViewer:

• form
  • components
  • currentCommand
  • commonScripts
  • form
  • input
  • label
  • button
  • message
  • row
  • rows
  • debugString

FormModel

This object contains information about the form data and form components, as well as directives used to render the form.

FormDataModel

This object contains information about a single Activiti FormData object for the form, either a Task form or a Start form, depending on usage.

FormComponentModel

This object, accessible through ${form.components[_componentname_]} (e.g form.components["task.description"] to access the component named “task.description”), contains information about a single form component. Note that the component models are only available after the component has been created through a form.input reference during the initial rendering; this means that the model is always available after a redisplay of the form (e.g. if validation fails, or if you use a command which does not submit data), but that the first time you display the form, the component does not exist prior to the form.input reference.

Example:

<!-- Bind and value will be empty on initial rendering -->
Description: Bind=${form.components["task.description].bindExpression!}: Value=${form.components["task.description].value!}<br />

[@form.form debug="true"]
   ...
   [@form.input name="task.description" /]                  <!-- Creates the component during initial rendering -->
   ...
[/@form.form]

<!-- Bind will not be empty during initial rendering; value might be (depends on Activiti form defintition -->
Description: Bind=${form.components["task.description].bindExpression!}: Value=${form.components["task.description].value!}<br />

FormDirective

This directive is used to render a <form> html tag. The directive must be closed at the end.

Example:

[@form.form debug="true"]
...
[/@form.form]

FormInputDirective

This directive is used to create a form component and render an input field for a data model item. The directive will automatically adapt its defaults according to the underlying data object’s semantics.

The input fields can take many different forms, depending on its type. The type is initially decided from the underlying data field, such that a numeric field will render as a number field. You can also specify a type manually to override this; this is particularly useful when a single field type has many possible renderings (such as a list of values, which can render as select or radio, and sometimes even as a popup).

Examples:

<!-- Default input field -->
[@form.input name="task.title" /]

<!-- Text area and tinymce editor -->
[@form.input name="description" bind="task.description" type="textarea" /]
[@form.input name="content"     bind="task.content" type="tinymce" tinymce="small"/]

<!-- Renders a dimension navigator, a drop-down to select dimensions and a user popup to select user, based on attribute definitions -->
[@form.input name="dimNavPopup"  bind="task.organization" attribute="MY_ORG_DIM_ATTRIBUTE" /]
[@form.input name="dimNavSelect" bind="task.brand"        attribute="MY_BRAND_DIM_ATTRIBUTE" /]
[@form.input name="userPopup"    bind="task.manager"      attribute="MY_USER_ATTRIBUTE" /]

FormLabelDirective

This directive is used to render a label for a data model item, using the label defined in the underlying data model. For example, an Activiti Task item will have an attached label that you can render using this directive.

Example:

[@form.label bind="task.description" /]

FormButtonDirective

This directive is used to render an action button for the form.

Examples:

<!-- Simple save-action -->
[@form.action name="submit" action="submit"]Complete task[/@form.action]

<!-- Three buttons, typically used on page 3 in a wizard. Use ${form.currentCommand.name} to decide which page to display -->
[@form.action name="page2"]Previous[/@form.action]
[@form.action name="page2"]Next[/@form.action]
[@form.action name="submit" action="submit"]Complete task[/@form.action]

FormMessageDirective

This directive is used to render a message for a component of the form. Messages are typically the result of validation failures (for most input fields), but are also used to store errors occuring during action processing.

Examples:

<!-- A typical scenario rendering a label, an input field and an error message -->
<tr>
<td>[@form.label bind="task.valuelist" /]</td>
<td>[@form.input name="task.valuelist" attribute="SYSTEST_ATTR_VALUELIST" /]</td>
<td>[@form.message for="task.valuelist" class="validationerror" /]</td>
</tr>

<!-- Renders an error message for a "submit" button -->
[@form.action name="submit" action="submit"]Complete task[/@form.action]
[@form.message for="submit" class="validationerror" /]