Form Processor Macros

The iKnowBase Presentation Services' Form Processor provides directives used to render form elements in a plugin development environment.

Requirements:

• Plugin development environment (See iKnowBase Development Toolkit for Java).
• Spring Controller with
  • iKnowBase Presentation Services Form Processor with
    • A backing bean containing properties with iKnowBase AttributeMapping-annotations (the directives are only available for these properties)
    • With explicit registration/enabling of the Plugin form macro
  • FreeMarker view

Overview

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

• form
  • input
  • label
  • bindingFieldErrors
  • message
  • resources

Note: “form” is the default and recommended name, but it may be changed when you register the form macro on the Form Processor.
Note: The model name “form” is also used by the Activiti Form Viewer.

FormModel

This object contains directives used to render form elements for backing bean properties annotated with iKnowBase AttributeMapping.

FormInputDirective

This directive is used to create a form component and render an input field for an iKnowBase AttributeMapping-annotated bean property. The directive will automatically adapt its defaults according to the annotations present on the property, including the referenced iKnowBase attribute definition.

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="title" /]

<!-- Renders a dimension navigator, a drop-down to select dimensions and a user popup to select user, based on attribute definitions and explit forced type -->
[@form.input name="organization" type="popup" /] <!-- NOTE: popup is default and therefore optional on this attribute -->
[@form.input name="brand" type="select" /]
[@form.input name="manager" type="popup" /]

FormLabelDirective

This directive is used to render a label for an iKnowBase AttributeMapping-annotated bean property, using the langiage specific label defined for the attribute.

Example:

[@form.label name="description" /]

FormBindingFieldErrors

form.bindingFieldErrors can be used both as a directive and as a model:

• As Directive: Render a message for a component of the form. Messages are typically the result of data mapping or validation failures (for most input fields) according to the bean validation rules set on the backing bean.
• As Model: Both a freemarker sequence and hash model, so you can access the nodes directly using ${form.bindingFieldErrors[index]}, or you can traverse it using the ...[/#list] syntax.

Examples:

<!-- A typical scenario rendering all error messages for all form fields -->
[@form.bindingFieldErrors separator="<br>" class="error" /]

<!-- A typical scenario rendering a label, an input field and an error message -->
<tr>
<td>[@form.label name="title" /]</td>
<td>[@form.input name="title" /]</td>
<td>[@form.bindingFieldErrors name="title" separator="<br>" class="error" /]</td>
</tr>

<!-- All errors -->
[#list form.bindingFieldErrors! as fieldError]
    ${fieldError.field} - ${fieldError.rejectedValue!} - ${fieldError.defaultMessage!} - ${fieldError.localizedMessage!} <br />
[/#list]

<!-- Errors for documentType property only --> 
[#list form.bindingFieldErrors.documentType! as fieldError]
    ${fieldError.field} - ${fieldError.rejectedValue!} - ${fieldError.defaultMessage!} - ${fieldError.localizedMessage!} <br />
[/#list]

FormMessageDirective

This directive is used to render a language specific message for a given code contained within the Form Processor’s MessageSource (you’ll specify it during construction of the Form Processor), which may contain a set of property files specific for your plugin.

[@form.message code="myLocalizedFormTitle" default="A default form title" /]

FormResourcesDirective

This directive is used to render html for including the external resources required by the Plugin form macro directives.

[@form.resources /]