Magnolia 5.4 reached end of life on November 15, 2018. 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 components for easy creation of standard forms, like contact forms. You can group related form elements such as address fields together visually. Form data can be validated using configurable validators. By default, submitted form data is sent by email. You can process form data with pluggable data processors which allow customization without changing the Magnolia core system. Magnolia forms are fully HTML5 compliant.
The Form module uses the Mail module to send form data in emails. See Configuring SMTP to enable mail sending.
See an example form on the Contact page of the Travel demo.
To create a form:
Add the Form component, to any area of a new or existing template.
Example: Adding form
component to main
area of a new template.
templateScript: /my-module/templates/pages/form-page-template.ftl renderType: freemarker visible: true title: Form Template dialog: my-module:pages/form areas: main: availableComponents: form: id: form:components/form
Node name | Value |
---|---|
my-module | |
templates | |
pages | |
form | |
areas | |
main | |
availableComponents | |
form | |
id | form:components/form |
dialog | my-module:pages/form |
renderType | freemarker |
title | Form Template |
templateScript | /my-module/templates/pages/form-page-template.ftl |
visible | true |
Add a field set component to the form.
You can have multiple field sets in the one form. This helps to groups them visually. For example contact details in one set and feedback message in another etc.
See an example multistep form on the Book your tour page of the Travel demo.
Splitting a large form into multiple steps allows the visitor to focus on one step at a time. The substeps are detected 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.
Add the Form Step component to an area of a template.
Example: Adding formStep
component to main
area in a new template.
templateScript: /my-module/templates/pages/formStep-page-template.ftl renderType: freemarker visible: true title: Form Step Template dialog: my-module:pages/form areas: main: availableComponents: form: id: form:components/formStep
Node name | Value |
---|---|
my-module | |
templates | |
pages | |
formStep | |
areas | |
main | |
availableComponents | |
formStep | |
id | form:components/formStep |
dialog | my-module:pages/form |
renderType | freemarker |
title | Form Step Template |
templateScript | /my-module/templates/pages/formStep-page-template.ftl |
visible | true |
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 displays step-by-step breadcrumb navigation that allows the user to navigate the steps of multistep forms. |
Submit settings tab
Field | Description |
Error title | Title displayed when an error occurs, for example "There was a problem with your booking." |
Success title | Title displayed when the form is submitted successfully, for example "Your tour is booked" |
Text | Text displayed when form is submitted successfully, for example "Details are on their way to your inbox." |
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. This can be any address as it is not the account used to send the mail. The mail is sent using the account in SMTP configuration . |
To | Email address the data is sent to. You can use form field names with Freemarker tags. Typically you would ask the submitting user for their email address on the form and repeat it here with a Freemarker tag such as |
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 | Displays a text field to compose the email template. You can use form field names with Freemarker tags such as |
html | Displays a Rich text 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, for example "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. |
Mail type | Radio button to select the message type. For code and text you can use form field names with Freemarker tags such as |
code | Displays a Code field (includes syntax highlighting) to compose the email template. |
text | Displays 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:
formGroupFields
Field components are added within a field set.
Available fields:
Field | Description | Image | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
Input |
Advanced options: Not all input types and attributes are supported in all browsers.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Number or date |
Advanced options: Not all input types and attributes are supported in all browsers.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Text field group |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Selection |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
File |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Submit button |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Hidden |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Honeypot |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Form summary |
|
Users are allowed to enter HTML-like characters such as ampersand (&) into fields. Use the noHTML validator to prevent this. You can control HTML escaping with the escapeHtml
property in the component definition.
5.4.4+ Password field is deprecated. Use two Input fields with input type Password instead. Validate the second field using the Password validator.
The Condition list component provides optional, additional business logic to a multistep form.
Validators are used to ensure that form data is entered in the correct format. For example, an email address should follow established syntax where a local part is followed by the @ character and a domain: john.smith@example.com
.
Choose a validator for appropriate fields in the Validation field.
When field validation passes, the value is submitted. When field validation fails, the field is highlighted in red and when the user attempts to submit the form a notification message identifies the problem.
Validators are configured in /modules/form/config/validators/
:
Node name | Value |
---|---|
form | |
config | |
validators | |
email | |
class | info.magnolia.module.form.validators.RegexValidator |
expression | (^([a-zA-Z0-9_\.\-+])+@(([a-zA-Z0-9-])+\.)+([a-zA-Z0-9]{2,4})+$) |
number | |
noHTML | |
class | info.magnolia.module.form.validators.NoHTMLValidator |
password | |
fileUpload | |
username | |
uniqueEmail | |
empty |
Properties:
validators | required Validator configuration node |
| required Name of the validator. |
| required Validator class that performs the validation. |
| required/optional Available properties depend on the validator class. |
Validator configurations:
email | Value needs to be a valid email address. Properties:
| ||||||
number | Value needs to be a number, specifically an integer. No decimals separated with period or comma or fractions are accepted. Properties:
| ||||||
noHTML | Value cannot any have HTML markup. This ensures that users can only enter plain text. Creating links and formatting text is prevented. Property:
| ||||||
password | Validates that the password entered into two password fields match. Used to eliminate typos. Property:
| ||||||
fileUpload | Validates against a list of allowed mime types and a max file size. Properties:
| ||||||
empty | No validation. Used for Honeypot field only. Properties:
| ||||||
username | Verifies that the entered username does not exist in the system. This validator is added by the Public User Registration (PUR) module.
| ||||||
uniqueEmail | Verifies that the entered email does not exist in the system. This validator is added by the Public User Registration (PUR) module.
|
Form processors configured in the module are responsible for sending submitted form data by email and storing it in the repository. The processors are executed when the form is submitted. The email content corresponds with the settings configured in the relevant tabs of the Form component.
Processors are configured in /modules/form/templates/components/form/formProcessors
.
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 |
Properties:
formProcessors | required Form processor node. |
| required Name of the form processor. |
| required
|
| optional, default is Enables and disables the processor |
| required The logger name. Only relevant for |
The three example form processors above send the form data in email, but you can write a custom form processor to do almost anything. If you need to store the data in a database or process it in another way, write your own form processor. You can also 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
.
Node name | Value |
---|---|
form | |
templates | |
components | |
form | |
formFile | |
formEdit | |
formStep | |
formHidden | |
formSubmit | |
formSummary | |
formPassword | |
formHoneypot | |
formGroupEdit | |
formCondition | |
formSelection | |
formGroupFields | |
formGroupEditItem |
escapeHtml
property escapes any HTML code entered in a form input field. This is a security feature that prevents XSS attacks. Default is true
for all form fields.To log data sent in the contact form:
trackEmail
form processor.magnolia-form.log
and click View. OR/webapps/<webappName>/logs/magnolia-form.log
on the file system.