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.
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 textselect
: selectionmultiselect
: multiple selectionfile
: a file to be uploadedboolean
: a boolean valuedate
: a datemonth
: monthrequired
: specifies whether the field is obligatory.flags
: a comma-separated list of display properties.value
: a preset value for the text
typevalidator
: 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
fieldserror
: 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.
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 URLFor 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 occurredHow the fields are displayed can be influenced by flags in the following way:
area
(text
): multi-line text inputpassword
(text
): invisible (hidden) text inputsorted
(select
, multiselect
): sort entries alphabeticallymenu
(select
, multiselect
): selection from a drop-down menuThe 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.
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.
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.
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.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.