Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
The Form module allows you to create Web forms that visitors can fill in. The module provides pre-configured form templates for easy creation of standard forms, like contact forms. Multiple form elements that belong together, like address fields, can be grouped visually. Form data can be validated using configurable validators. By default, data is sent via email in HTML or plain text or logged to the file system. Form data is processed using pluggable data processors which allow customization without changing the Magnolia core system. For information on working with components to create forms, see Form components .
The Form module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository
Form is a Community Edition module. It is typically already installed. Launch the Configuration app and go to /modules/form
to check.
The Form module is configured at /modules/form
.
Node name | Value |
---|---|
form | |
config | |
templates | |
dialogs |
The Form module uses the Mail module to send form data in emails. See Configuring SMTP to enable mail sending.
/demo-project/service/contact
page.Add a field set component to the form.
Splitting a large form into multiple steps allows the visitor to focus on one step at a time. The substeps are detected by Magnolia automatically. Visitors can move forward and backwards between steps without losing entered data. Each step is validated individually. The form module also allows users to upload files, but the upload field should only be included as the last step of the process. A pluggable model allows you to dynamically select a next step based on custom business logic. You can view an example mulitstep on the demo-features/special-templates/multi-step-form
page.
To create a multistep form:
Form settings are configured in the Form component.
Form tab
Field | Description |
---|---|
Title | Title displayed above the form. For example "Contact Us". |
Form name | Internal name that allows you to reference the form by name, for example from JavaScript. |
Text | Introductory text displayed below the form title. |
Marker for required fields | Character displayed next to required fields. Asterisk by default. |
Text for required symbol | Text that explains what the required marker means, displayed near the top of the form. For example "Required fields". |
Step-by-Step Navigation | When checked will display a numbered list of the step page-titles after form title and text to navigate through steps of multistep forms. |
Submit settings tab
Field | Description |
---|---|
Error title | Title displayed when an error occurs. |
Success title | Title displayed when the form is submitted successfully, for example "Thank you!" |
Text | Text displayed when form is submitted successfully, for example "Your details have been submitted." |
Page displayed after submission | Select a page to display after submission. If no page is selected, the user stays on the current page and the success title and text are displayed instead. |
Track mail | Logs the information submitted in the form to |
Email tab
Field | Description |
---|---|
From | Email address displayed in the From field of the outgoing message. Typically you would ask the submitting user for their email address on the form and repeat it here with a Freemarker tag such as |
To | Email address the data is sent to. You can use form field names with Freemarker tags. |
Subject | Email subject line. You can use form field names with Freemarker tags such as |
Available fields for Freemarker syntax | Form field names that can be used in Freemarker tags. |
Type | Radio button to select the message type for the email body. |
text | Opens a text field to compose the email template. You can use form field names with Freemarker tags such as |
html | Opens a fckEdit field to compose the email template. You can use markup that will be escaped. |
Confirmation email tab
Field | Description |
---|---|
Send confirmation | Sends a confirmation mail to the submitting user. |
From | Email address displayed in the From field of the outgoing message. You might want to use a customer support address here in case the user has further questions or a no-reply address. You can use form field names with Freemarker tags. |
To | Email address the data is sent to. You can use form field names with Freemarker tags such as |
Subject | Email subject line such as "We have received your feedback". You can use form field names with Freemarker tags such as |
Available fields for Freemarker syntax | Form field names that can be used in Freemarker tags. |
Type | Radio button to select the message type. For code and text you can use form field names with Freemarker tags such as |
code | Opens an editCode field (includes syntax highlighting) to compose the email template. |
text | Opens a text field to compose the email template. |
page | A page in the site that the user is sent to after successful submission. |
The purpose of a field set is to group fields that logically belong together: Before you can add any fields on the form you need to add at least one field set component:
See Form module components for fields that you can add into a field set.
Validators are used to ensure that form data is entered in correct format and length. For example, an email address should adhere to an established syntax where a local part is followed by the @ character and a domain: john.smith@example.com
. Validators are configured in /modules/form/config/validators/
. The validation is performed by a Java class referenced in the class
node. The Form module provides the following validators out-of-the-box:
empty
No validation. Used for Honey pot field only. email
Value needs to be a valid email address. Validity is checked with regular expression ^\S+@\S+$
. This validator uses the
ValidateExpression
class that evaluates a regular expression configured in the expression
property.number
Value needs to be a number, specifically an integer. No decimals separated with period or comma or fractions are accepted. Validity is checked with regular expression [0-9]*
noHTML
Value cannot any have HTML markup. This ensures that users can enter only plain text. Creating links and formatting text is prevented. Validity is checked with the custom
NoHTMLValidator
class that checks for the presence of angle brackets (<
>
).password
Validates that a password typed into the user profile update form matches the one typed into the confirmation field. Used to eliminate typos. Uses the
PasswordValidator
class.username
Verifies that the entered username does not exist in the system. The Java class for this validator is in the Public User Registration (PUR) module.fileUpload
Verifies the mime type and the size of an uploaded file.maxFileSize
has default value of 10485760allowedMimeTypes
: "default" values are not set on the calls bot bootsrapped as shown below {application/pdf, image/gif, image/jpg, image/jpeg, image/png}; adapt the list according to your requirementsNode name | Value |
---|---|
form | |
config | |
validators | |
none | |
class | info.magnolia.module.form.validators.ValidateExpression |
expression | (^$|^\S+@\S+$) |
noHTML | |
number | |
password | |
class | info.magnolia.module.form.validators.PasswordValidator |
fileUpload | |
class | info.magnolia.module.form.validators.FileUploadValidator |
i18nBasename | info.magnolia.module.form.messages |
maxFileSize | 12345678 |
allowedMimeTypes | |
1 | application/pdf |
2 | image/gif |
3 | image/jpg |
4 | image/jpeg |
5 | image/png |
username | |
empty | |
templates | |
dialogs |
Configured validators are displayed as options in a the Field dialog when fields are added to the form. When field validation passes, the value is submitted. When field validation fails, a message is displayed to the user identifying the problem field. See Field validators for more information.
Form processors are responsible for sending the submitted form data in email or storing it in the repository. Processors are configured in /modules/form/templates/components/form/formProcessors
and executed when the corresponding form is submitted.
The following configurable processors are provided out-of-the-box:
enabled
property under the processor and set its value to true
.magnolia-form.log
file if the Track Mail checkbox is checked. By default, this processor is not enabled. This is the case even if the Track Mail checkbox is checked in form settings. To enable it, add an enabled
property under the processor and set its value to true
.Node name | Value |
---|---|
form | |
templates | |
components | |
form | |
formProcessors | |
sendContactEmail | |
class | info.magnolia.module.form.processors.SendContactEMailProcessor |
enabled | true |
sendCofirmationEmail | |
class | info.magnolia.module.form.processors.SendConfirmationEmailProcessor |
enabled | true |
trackEmail | |
class | info.magnolia.module.form.processors.TrackEmailProcessor |
enabled | true |
loggernName | log-form |
The three example form processors above send the form data in email. If you need to store the data in a database or process it in another way, write your own form processor. You can also use try the Form2DB App that is a community developed app that saves form data via form processor into the JCR and allows for export to XLS.
Create a new form component definition for your custom processor. If you simply add the custom processor to the default component definition it will be executed for all forms.
For more examples see Form processors in the PUR module.
The form components are configured in /modules/form/templates/components
. Form components are standard Magnolia components configured in the same way as all components.
Node name | Value |
---|---|
form | |
templates | |
components | |
form | |
formFile | |
formEdit | |
formStep | |
formHidden | |
formSubmit | |
formSummary | |
formPassword | |
description | paragraph.formPassword.description |
dialog | form:formEdit |
escapeHtml | false |
i18nBasename | info.magnolia.module.form.messages |
modelClass | info.magnolia.module.form.templates.components.FormFieldModel |
renderType | freemarker |
templateScript | /form/components/formPassword.ftl |
title | paragraph.formPassword.title |
formHoneypot | |
formGroupEdit | |
formCondition | |
formSelection | |
formGroupFields | |
formGroupEditItem |
The escapeHtml
property escapes any HTML code entered into a form input field. This is a security feature that prevents XSS attacks. Default is true
for all form fields except password where default is false
. This allows users to include characters like "&" that are typically found in passwords.
To log data sent in the contact form:
trackEmail
form processor.magnolia-form.log
and click View. ORwebapps/<webappName>/logs/magnolia-form.log
on the file system.Multi-step forms were introduced in Magnolia 4.4, meaning that individual form pages and the first page of a multi-step from needed to be excluded from cache to prevent 'session expired' errors. 4.4.6+ Abstract FormModel sets the no-cache header automatically.
The Form module keeps the internal state on the server. It is kept in session using a unique ID for each user interaction and this makes it possible to have simultaneous form interactions in a single session, for example in multiple tabs. A unique ID is rendered within the page as a hidden input field. This is the reason the page needs to be excluded from caching; otherwise different users would be able to use the same ID that was used when the page went into the cache. Pages can be excluded from the cache in the Cache module at Configuration > /modules/cache/config/configurations/default/cachePolicy/voters/urls/excludes
.