Form module

Content management Bundled: Community Edition

Edition	CE
License	MLA, GPL
Issues	MGNLFORM
Maven site	Form
Latest	2.7.8
Available on SPA/Headless	No

Edition

License

MLA, GPL

Issues

MGNLFORM

Maven site

Form

Latest

2.7.8

Available on SPA/Headless

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.

Please note that the artifact IDs (Maven groupId and artifactId) have changed since Magnolia 5.5.

If you have custom Java code relying on this module, you need to install a compatibility module too.

Check Git for the new module structure.

Installing with Maven

Bundled modules are automatically installed for you.

If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section. If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies> section.

<dependency>
  <groupId>info.magnolia.form</groupId>
  <artifactId>magnolia-form</artifactId>
  <version>2.7.8</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Note the changes in groupId and artifactId since the 2.4 release.

Compatibility module

We have been gradually removing the old Content API from our modules since Magnolia 5.6. If you have custom code relying on classes from the old Form module, you must do one of two things:

Update your code for the new version of the Form module.
Use the magnolia-form-compatibility module together with the magnolia-core-compatibility module.

Add the following snippet to your POM file:

<dependency>
  <groupId>info.magnolia.form</groupId>
  <artifactId>magnolia-form-compatibility</artifactId>
  <version>2.7.8</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Mail configuration

The Form module uses the Mail module to send form data in emails. See Configuring SMTP to enable mail sending.

Creating a form

See an overview of differences between FreeMarker and headless templating.

See an example form on the Contact page of the Travel Demo.

The Travel Demo uses several GDPR-ready form components. The (GDPR) Store data form in the Travel Demo is equivalent to the form component below.

To create a form:

Add a form component to any area of a new or existing template.
Example: Adding the form component to the main area of a new template.

/my-module/templates/pages/form.yaml

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

Create a new page based on the template that contains the form component (created above).
Open the page, add the form component and configure the form settings. Form settings define the title and name of the form and where the collected information should be submitted.
Add a field set to the form.

You can have multiple field sets in one form. This helps group them visually (for example, contact details in one set and feedback messages in another).
Add fields inside the field set.
View the form.

Creating forms for handling personal data

With Magnolia, you can create forms for the purpose of handling personal data such as for the requirements of General Data Protection Regulation (GDPR).

Magnolia provides the following pre-configured GDPR-related form templates as samples you can build on:

Sample form Used to create Provided by

Store data form, Confirm data form

Double opt-in forms.

See an example of creating a form with double opt-in functionality on the Creating a GDPR-compliant form page.

privacy-sample module

Get visitor data form

Forms where the user can request a zipped report listing their personal data stored by the site.

privacy-form module

Forget me form

Forms where the user can request deletion of their personal data.

privacy-form module

Delete visitor form

Forms where the user can confirm a request for deletion of the user’s personal data

privacy-form module

Personal data form processors

To implement the above functions, the magnolia-privacy module provides the following form processors:

info.magnolia.privacy.form.processor.AddConsentFormProcessor: Updates a visitor’s consent.
- info.magnolia.privacy.form.processor.JcrStoreFormProcessor: Extends the functionality of the AddConsentFormProcessor processor. It also stores the data into a JCR workspace. The data is stored in an intermediate workspace so that the data cannot be used unless the visitor confirms consent. Under the processor define:
  - workspace - the name of the intermediate workspace.
  - nodeNameProperty - the node name of the data to be stored.
  - nodeType - the node type of the data to be stored.
  - rootPath - the path to the node (default is /).
- info.magnolia.privacy.form.processor.JcrMoveFormProcessor: Moves data from the intermediate workspace to the target workspace. Configure the intermediate and target workspaces under the processor using the sourceWorkspace and targetWorkspace properties.
info.magnolia.privacy.form.processor.ConfirmConsentFormProcessor: Confirms a visitor’s consent.
info.magnolia.privacy.form.processor.GetVisitorDataFormProcessor: Collects all data belonging to a visitor and provides a weblink where the visitor can download this data.
DeleteVisitorFormProcessor: Requests the deletion of all a visitor’s data (via a deletionId).
info.magnolia.privacy.form.processor.ConfirmVisitorDeletionFormProcessor: Confirms the deletion request.

See GDPR and forms too.

Creating a multistep form

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 a form step component to an area of a template.
Example: Adding the formStep component to the main area in a new template.

/my-module/templates/pages/form.yaml

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

Create a new page based on a template that contains the form component. This is the first page of the form.
1. Configure the form settings.
2. Add a field set component
3. Add fields inside the field set. The Submit button field will automatically navigate to the next step. Conditional steps can be set in the next step condition component.
Create subpages based on the template that contains the form step component (created above) for the subsequent steps of the form.
1. Add field sets and fields to the substep forms. The Submit button field will automatically navigate to subsequent or conditional steps, and the final button will submit the form.

Configuring form settings

Form settings are configured in the form component.

Form tab

Field Description

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.

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 the 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 the magnolia-form.log file.

Make sure the trackEMail form processor is also enabled. See Logging form data.

Email tab

Field Description

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 `${email}` assuming the email field is named `email`.
Subject	Email subject line. You can use form field names with Freemarker tags such as `${subject}`.
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 `${subject}` and `${message}` to write the data collected on the form into the message.
html	Displays a rich text field to compose the email template. You can use markup that will be escaped.

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.

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 ${email} assuming the email field is named email.

Subject

Email subject line. You can use form field names with Freemarker tags such as ${subject}.

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 ${subject} and ${message} to write the data collected on the form into the message.

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.

Make sure the SendConfirmationEMailProcessor form processor is also enabled.

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.

Email address the data is sent to. You can use form field names with Freemarker tags such as ${email}.

Subject

Email subject line, for example We have received your feedback. You can use form field names with Freemarker tags such as ${subject}.

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 ${subject} and ${message} to write the data collected on the form into the message. This can be a simple acknowledgement that data was submitted or you can summarize the collected data.

Type: code

Displays a code field (includes syntax highlighting) to compose the email template.

Type: text

Displays a text field to compose the email template.

Type: page

This option means that the content of a page is sent to the user. The internal process reads the page content, pastes the content in the body of the email, and sends the mail to the user.

The page itself, however, does not need to be available to the visitor.

Field sets

The purpose of a field set is to group fields that logically belong together:

Before you can add any fields to the form, you need to add at least one field set component.
You can add as many field sets as necessary.
Use the Title field to distinguish field sets or include introductory text.
Individual field components are added as subcomponents in a field set.
Component definition: formGroupFields

Field sets

Fields

Field components are added within a field set.

Available fields:

Field Description

Input

Single line text input or text area.
Maximum input length option.
Component definition: formEdit.

Advanced options: Not all input types and attributes are supported in all browsers.

Types HTML5-compliant input type

Color

<input type = color>. To select a color from a pop-up color picker.

Color field

<input type = email>. Email field. Most browsers automatically validate content. Additionally, you can use an email validator.

Email field

Password

<input type = password>. Password field. The characters are masked with asterisks or circles.

Password field

<input type = search>. Search field. Behaves like a regular text field.

Text

<input type = text>. Standard text field.

Url

<input type = url>. For fields that should contain a URL address. Most browsers validate automatically.

URL field

Attributes

Placeholder

Hint that describes the expected value.

Pattern

Regular expression that the input value is checked against. For example, [A-Za-z]{3} for a three-letter country code.

Please note that this attribute has no effect at this time. We are aware of this issue and working on a bugfix for this: MGNLFORM-296.

As a temporary workaround, you can configure the regex expression as a separate validator for the field under /modules/form/config/validators.

Pattern field

Pattern description

Use the field description to help guide the user instead.

Read only

Boolean attribute that sets the field as read-only. User cannot enter input but can tab to it, highlight it, and copy from it.

Disabled

Boolean attribute that disables the input field. The field is unusable and unclickable. Typically used to prevent the user from entering input until another condition is met.

Disabled field

Autofocus

Boolean attribute that places the cursor in the focused field on page load.

Autocomplete

Enables autocomplete which allows the browser to predict the value based on earlier typed values. Submit information and then reload the page to test.

Autocomplete field

Number or date

Number or date field.
Maximum input length option.
Component definition: formNumber (extends formEdit).

Advanced options: Not all input types and attributes are supported in all browsers.

Types HTML5-compliant input type

Date

<input type = date>. To enter or select a date.

Date field

Datetime

<input type = datetime>. To enter or select a date and time with a timezone.

This type is no longer supported by the latest HTML standards. See html.spec.whatwg.org/dev/input.html and www.w3.org/TR/html5/sec-forms.html.

Modern browsers may differ in how they render this type, most of them displaying a simple text field instead.

Datetime field

Datetime-local

<input type = datetime-local>. To enter or select a date and time (no time zone).

Datetime local field

Month

<input type = month>. To enter or select a month and year.

Month field

Number

<input type = number>. To enter or select a numeric value.

Number field

Phone number

<input type = tel>. For fields that should contain telephone numbers. Only supported in Safari 8.

Range

<input type = range>. For fields that should contain a value within a range.

Range field

Time

<input type = time>. To select a time (no time zone).

Time field

Week

<input type = url>. To select a week and year.

Week field

Attributes

Read only

See Input field.

Disabled

See Input field.

Autofocus

See Input field.

Autocomplete

See Input field.

Minimum

Minimum value for the field.

Maximum

Maximum value for the field.

Step

Number intervals for the field. For example, if step=3, legal numbers could be -3, 0, 3, 6, etc.

Text field group

Groups text fields next to each other.
The Group dialog has a single field that does not appear on the page. Assign this name to reference the group with FreeMarker tags.
The subcomponents are text fields, i.e. input fields without advanced options.
Component definition: formGroupEdit that nests formGroupEditItem components.

Selection

Checkbox, select and radio buttons.
Multiple selection, default value and orientation options.
Component definition: formSelection.

File

Upload file component.
In multistep forms, this is only available in the last step.
Component definition: formFile.

Submit button

Submits the form.
Can be labeled as required.
Cancel button and Back button options (in multistep forms).
The component should be added at the end of the form.
Component definition: formSubmit.

Hidden

Single hidden line input or text area.
Does not appear on the page.
Used to pass on values to form processors in the same way as data entered by a user.
Component definition: formHidden.

Honeypot

This is an invisible field that you can add to the page to intercept bot attacks.
Component definition: formHoneypot.

Form summary

Displays a table with parameters and/or values of the steps in a multistep form.
Component definition: formSummary.

Users are allowed to enter HTML-like characters such as & into fields. Use the noHTML validator to prevent this. You can control HTML escaping with the escapeHtml property in the component definition.

Conditional steps

The condition list component provides optional, additional business logic to a multistep form.

The component is added automatically after the Submit button field as an optional area.
It allows you to set conditions for subsequent steps in a multistep form.
It lets you define the page the user is directed to based on what they previously entered.

Field validators

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.doe@example.com).

Choose a validator for appropriate fields in the Validation field.

Input field tab in edit mode

When field validation passes, the value is submitted. When field validation fails, the field is highlighted in red; when the user attempts to submit the form, a notification message identifies the problem.

Validator example

Validators are configured in /modules/form/config/validators/:

Validator configuration

Property Description

Property	Description
`validators`	required Validator configuration node
`<validator name>`	required Name of the validator.
`class`	required Validator class that performs the validation.
`<validator properties>`	required/optional Available properties depend on the validator class.

validators

required

Validator configuration node

<validator name>

required

Name of the validator.

class

required

Validator class that performs the validation.

<validator properties>

required/optional

Available properties depend on the validator class.

Validator configurations:

Property Description

email

Value needs to be a valid email address.

class

required

info.magnolia.module.form.validators.RegexValidator

expression

required

Validity is checked with regular expression (^([a-zA-Z0-9_\.\-+])+@(([a-zA-Z0-9-])+\.)+([a-zA-Z0-9]{2,4})+$).

number

Value needs to be a number, specifically an integer. No decimals separated with period or comma or fractions are accepted.

class

required

info.magnolia.module.form.validators.RegexValidator

expression

required

Validity is checked with regular expression ^[0-9]*$.

noHTML

Value cannot any have HTML markup. This ensures that users can only enter plain text. Creating links and formatting text are not allowed.

class

required

info.magnolia.module.form.validators.NoHTMLValidator

Custom class that checks for the presence of angle brackets (< >).

password

Validates that the passwords entered into two password fields match. Used to eliminate typos.

class

required

info.magnolia.module.form.validators.PasswordValidator

The fields should be named password and passwordConfirmation.

fileUpload

Validates against a list of allowed MIME types and a maximum file size.

class

required

info.magnolia.module.form.validators.FileUploadValidator

maxFileSize

optional, default is 10485760

Maximum file upload size.

allowedMimeTypes

optional

Content node for a list of allowed MIME types. Add a property for each additional type. By default, application/pdf, image/gif, image/jpeg, image/jpg and image/png are allowed.

empty

No validation. Used for the honeypot field only.

class

required

info.magnolia.module.form.validators.RegexValidator

expression

required

- (dash/null)

username

Verifies that the entered username does not exist in the system. This validator is added by the Public User Registration (PUR) module.

class

required

info.magnolia.module.publicuserregistration.validators.UsernameValidator

uniqueEmail

Verifies that the entered email does not exist in the system. This validator is added by the Public User Registration (PUR) module.

class

required

info.magnolia.module.publicuserregistration.validators.UniqueEmailValidator

Form processors

Form processors configured in the module are responsible for sending submitted form data by email. 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.

Processors configuration

Property Description

Property	Description
`formProcessors`	required Form processor node.
`<form processor name>`	required Name of the form processor.
`class`	required `info.magnolia.module.form.processors.SendContactEMailProcessor`: Sends form data in email to the address specified in the To field. The processor extracts values from the From, To, Subject and Text fields and creates an email message in plain text or HTML format depending on form settings. Any uploaded files are sent as attachments. `info.magnolia.module.form.processors.SendConfirmationEMailProcessor`: Sends a confirmation email. The processor first verifies if the Send confirmation checkbox is checked and sends a message to the address specified in the To field. By default, this processor is not enabled. This is the case even if the Send confirmation checkbox is checked in form settings. To enable it, add an `enabled` property under the processor and set the value to `true`. `info.magnolia.module.form.processors.TrackEmailProcessor`: Writes the content of the submitted form to the `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 the value to `true`.
`enabled`	optional, default is `false` Enables and disables the processor
`loggerName`	required The logger name. Only relevant for the `trackEmail` processor.

formProcessors

required

Form processor node.

<form processor name>

required

Name of the form processor.

class

required

info.magnolia.module.form.processors.SendContactEMailProcessor: Sends form data in email to the address specified in the To field. The processor extracts values from the From, To, Subject and Text fields and creates an email message in plain text or HTML format depending on form settings. Any uploaded files are sent as attachments.
info.magnolia.module.form.processors.SendConfirmationEMailProcessor: Sends a confirmation email. The processor first verifies if the Send confirmation checkbox is checked and sends a message to the address specified in the To field. By default, this processor is not enabled. This is the case even if the Send confirmation checkbox is checked in form settings. To enable it, add an enabled property under the processor and set the value to true.
info.magnolia.module.form.processors.TrackEmailProcessor: Writes the content of the submitted form to the 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 the value to true.

enabled

optional, default is false

Enables and disables the processor

loggerName

required

The logger name. Only relevant for the trackEmail processor.

Creating a custom form processor

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.

You can also create a form processor with server-side JavaScript.

Form components

The form components are configured in /modules/form/templates/components.

Form components configuration

The escapeHtml property escapes any HTML code entered in a form input field. This is a security feature that prevents XSS attacks. The default is true for all form fields.
info.magnolia.module.form.templates.components.AbstractFormModel ensures that pages with forms are not cached.

Logging form data

To log data sent in the contact form:

In the form component, check the Track mail checkbox in the Submit settings tab.
Enable the trackEmail form processor.
Submit a form.
To view the log:
- Go to Tools > Log viewer, select magnolia-form.log and click View. OR
- Open /webapps/<webappName>/logs/magnolia-form.log in the file system.

Form module

Installing with Maven

Compatibility module

Mail configuration

Creating a form

Creating forms for handling personal data

Personal data form processors

Creating a multistep form

Configuring form settings

Field sets

Fields

Conditional steps

Field validators

Form processors

Creating a custom form processor

Form components

Logging form data

Location

Main doc sections