Form Portlet

The form portlet offers a simple way of providing a sequence of form pages.

Using this portlet requires a separate licence.

By means of the corresponding buttons, the user can move to the previous or next page of the sequence of forms. When the last form is submitted, normally an action is performed. For example, the form data can be sent via e-mail.

The forms and their sequence as well as the action to be performed at the end, are defined in an XML file. The dynamic display of the forms on the web page can be controlled by means of velocity templates.

Each sequence is defined in an individual directory below WEB-INF/templates/flow. The portlet can be integrated into the content by specifying the desired sequence definition directory. The definition always includes an XML file, flow.xml, in which the form pages and their fields are specified. Also, for each form page, a Velocity template used to generate the form's HTML code needs to be placed into the definition directory. These templates are referenced by the XML file. Furthermore, the definition includes the action mentioned above. This action is implemented by a Java class. For the purpose of illustrating a typical use case, the sample files for sending the form data via e-mail are included.

Configuration

Form Definitions

The form pages are defined in the file flow.xml. The root element of this file is always flow. Optionally, this element can have an attribute named result which defines the result template. If result has not been specified, result.vm will be used. Inside flow, each form page is defined by means of a form form element, and the final action is specified using an action element.

Each form element defines exacly one form page. By means of its template attribute, the name of the Velocity template is specified that serves to display this form page. This template file must be located in the same folder as the flow.xml definition file. An example:

<?xml version="1.0" encoding="UTF-8" ?>
  <flow>
  <form template="contact.vm">
    <field name="gender" type="select"
      required="true" flags="menu">
      <item default="true">female</item>
      <item>male</item>
    </field>
    <field name="firstName" type="text"
      regex="([\p{Lu}][\p{Ll}.-]* *)+" error="errorInvalidName" />
    <field name="lastName" type="text" required="true"
      regex="([-\p{Lu}\p{Ll}]+ *)+" error="errorInvalidName" />
    <field name="email" type="text"
      required="true" validator="email" />
    <field name="subject" type="text" required="true" />
    <field name="message" type="text"
      required="true" flags="area" />
  </form>
    <action name="sendEmail">
    <param name="receiver">playland@example.org</param>
    <param name="template">email.vm</param>
    <param name="senderField">email</param>
    <param name="subjectField">subject</param>
  </action>
</flow>

A form element may include any number of field elements. Each of them represents a field of the form page concerned. field elements can have the following attributes:

name: The name of the field which must be unique on the page.
type: The field type. The permitted types are defined in the WEB-INF/flow.properties file:
- text: simple text
- select: selection
- multiselect: multiple selection
- file: a file to be uploaded
- boolean: a boolean value
- date: a date
- month: month
required: specifies whether the field is obligatory.
flags: a comma-separated list of display properties.
value: a preset value for the text type
validator: a test for the value. Permitted tests are defined in the WEB-INF/flow.properties file.
regex: a regular expression for testing the value of text fields
error: the error which is output if the regex test fails, otherwise error errorInvalid.

The name and type attributes are obligatory. You can specify either the validator or regex attribute, not both. For the select and multiselect types, the available values can be specified by means of item elements in the field element. For select) and multiselect the preselected value or values, respectively, can be defined by means of the default="true" attribute of the item element concerned.

If the item element has a value attribute, its value is used as field value if the user has selected the element. The contents of the element, on the other hand, serves as display value. If value has not been specified, the localized contents of the item element is used as display value while the contents itself is used as the actual field value.

The final action needs to be defined by means of an action element. Its obligatory name attribute determines the action; the permitted names are again defined in the WEB-INF/flow.properties file. As for the tests, the action references a Java class which implements the action. The arguments to be passed to the Java code can be defined by means of param elements inside the action element. Each param element needs to have a unique name which can be specified as the value of its name attribute. The contents of such an element is the argument value.

Displaying the Forms with Velocity Templates

Each form page is displayed by means of a Velocity template. In the current context the following variables for accessing dynamic content are available:

$fields: all fields of the form page via their name
$errors: the list of all the errors that occurred
$text: localizations (see below)
$page: the number of the current page, beginning with 1
$pages: the total number of pages
$action: the form URL

For displaying the fields, several macros are available, originating from the WEB-INF/templates/flow/macros.vm file:

#renderLabel: displays a localized field title
#renderField: displays the fields in accordance with the type and the flags (see above)
#renderButtons: displays a list of buttons
#renderErrors: displays the errors that occurred

How the fields are displayed can be influenced by flags in the following way:

area (text): multi-line text input
password (text): invisible (hidden) text input
sorted (select, multiselect): sort entries alphabetically
menu (select, multiselect): selection from a drop-down menu

The following example template displays a contact form:

<form action="$action" method="post" class="contact">
  #renderErrors()
  <table cellpadding="0" cellspacing="0" border="0">
    <tr>
      <td class="contact">#renderLabel($fields.gender)
        <div>#renderSelectField($fields.gender)</div>
      </td>
      <td class="contact">#renderLabel($fields.lastName)<br>
        #renderTextField($fields.lastName)
      </td>
      <td class="contact">#renderLabel($fields.firstName)<br>
        #renderTextField($fields.firstName)
      </td>
    </tr>
    <tr>
      <td class="contact" colspan="3">
        #renderLabel($fields.email)<br>
        #renderTextField($fields.email)
      </td>
    </tr>
    <tr>
      <td class="contact" colspan="3">
        #renderLabel($fields.subject)<br>
        #renderTextField($fields.subject)
      </td>
    </tr>
    <tr>
      <td class="contact" colspan="3">
        #renderLabel($fields.message)<br>
        #renderTextField($fields.message)
      </td>
    </tr>
    <tr>
      <td class="contact" colspan="3">
        #renderButtons(["Ok"])
      </td>
    </tr>
  </table>
</form>

Please also take a look at the description of the Velocity syntax.

Localisation

In the form definition folder the localization for field titles, buttons, errors, and other texts are stored. You can access the localized strings inside templates by means of the text context variable. The localizations are stored in the directory as a „Java resource bundle" named localizer. It consists of one file for each language. This file is named localizer_Language.properties, with Language standing for a two-character language code such as en or de.

Buttons are normally prefixed with button, errors have the prefix error, and field titles are prefixed with the name of the corresponding field. Optionally, additional messages, for example for the action result, can be added.

Usage

The portlet can be included in the content by means of the following code:

<npspm includePortlet="flow" instance="flowname" />

flowname stands for the name of the directory containing the form sequence definitions.

When the portlet is executed it displays the first form page inside the portlet. Switches are used for navigating. Typically, these switches are displayed by means of #renderButtons. The meaning of the following named switches is predefined:

Cancel: aborts the form sequence, clears all data, and returns to the first page.
Back: jumps to the previous page if it exists. Entered data is preserved.

All other switches have the function of Continue oder OK. If such a switch is used on the last form page, the defined action is performed. If no error occurs during this action, the result is displayed by means of the result template.

If a field or the action itself causes an error, the current page is not left but displayed again including the errors. The errors should be displayed at a proper place on the page using the #renderErrors macro.

Example: Sending E-mail Messages

As a typical use case, an action for sending the form data as an e-mail message has already been implemented. The action sendEmail can be adapted to different requirements. For this, several arguments are available in the action element (see the example definition above):

receiver: the recipient or recipients of the message. If this argument is missing, the e-mail is sent to the sender.
template: the name of the e-mail template.
sender /senderField: the sender or the field from which the sender is taken. Please note that the sender must be accepted by the mail server!
subject / subjectField: the subject or the field, respectively, from which the subject of the message is taken.

Example: Sending E-Mail Messages and a Confirmation Message

In addition to the sendEmail action, sendEmailAndConfirmation has been implemented. This action can be used to send a confirmation message in addition to the e-mail message itself.

In the action element, sendEmailAndConfirmation has the same parameters as sendEmail, plus the following ones:

confirmationReceiverField: the field from which the recipient of the confirmation message is taken.
confirmationTemplate: the name of the template used for the confirmation message.
confirmationSubjectField: the field from which the subject of the confirmation message is taken.

Typically, the #renderValue and (from version 6.7.2) #renderHtmlEscapedValue macros are used to take over the field values into the template.