Form module

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.

Installing

<dependency>
  <groupId>info.magnolia.form</groupId>
  <artifactId>magnolia-form</artifactId>
</dependency>

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 then you must do one of two things:

• Update your code for the new version of the form module.
• Or you can use the magnolia-form-compatibility module together with the magnolia-core-compatibility module.

<dependency>
  <groupId>info.magnolia.form</groupId>
  <artifactId>magnolia-form-compatibility</artifactId>
</dependency>

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

To create a form:

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

   • YAML file
   • JCR node

   /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 

   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

2. Create a new page based on the template that contains the Form component (created in 1. above).
3. 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.
   

4. Add a fieldset to the form.
   

   You can have multiple field sets in one form. This helps to groups them visually. For example contact details in one set and feedback message in another etc.

5. Add a field set.
   
6. Add fields inside the field set.
   
7. View the form.
   

Creating forms for handling personal data

With Magnolia you can create forms for the purposes of handling personal data, for example 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:

Personal data form processors

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

• AddConsentFormProcessor: Updates a visitor's consent.
  
  • 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 "/").
  • 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.
• ConfirmConsentFormProcessor: Confirms a visitor's consent.
• 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).
• ConfirmVisitorDeletionFormProcessor: Confirms the deletion request.

See GDPR and forms too.

Creating a multistep form

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.

1. Add the Form Step component to an area of a template.
   Example: Adding formStep component to main area in a new template.

   • YAML file
   • JCR node

   /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

   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

2. 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.
      

      

3. Create subpages based on the template that contains the Form Step component (created in 1. above) for the subsequent steps of the form.
   
   1. Add field sets and fields on the substep forms. Submit button fields 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

Submit settings tab

Email tab

Confirmation email tab

Field sets

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.
• You can add as many field sets as necessary.
• Use the Title field to distinguish field sets or include introductory text.
• Individual fields components are added as subcomponents in a field set.
• Component definition: formGroupFields

Fields

Field components are added within a field set.

Available fields:

Field	Description	Image
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 Email <input type = email>. Email field. Most browsers automatically validate content. Additionally, you can use E-mail validator. Password <input type = password> . Password field. The characters are masked with asterisks or circles. Search <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.  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 - Getting issue details... STATUS As a temporary workaround, you can configure the regex expression as a separate validator for the field under /modules/form/config/validators . 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. Field is unusable and unclickable. Typically used to prevent user from entering input until another condition is met. 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.
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. Datetime <input type = datetime>. To enter or select a date and time with a timezone.  Datetime-local <input type = datetime-local>. To enter or select a date and time (no time zone). Month <input type = month>. To enter or select a month and year. Number <input type = number>. To enter or select a numeric value. 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.  Time <input type = time>. To select a time (no time zone). Week <input type = url>. To select a week and year. 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 display 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 on the last step. Component definition: formFile.
Submit button	Submits the form. Can be labelled as required. Cancel button and Back button (mulitstep forms) options. Component should be added at the end of the form. Component definition: formSubmit.
Hidden	Single hidden line input or text area. Does not display on the page. Used to pass on values to the form processors in the same way as other 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

Conditional steps

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

• The component is added automatically after a Submit button field, as an optional area.
• Allows you to set conditions for subsequent steps in a multistep form.
• Allows you to define the page the user is directed to, dependent on their entry in a former step. 
   
   

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.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/:

Properties:

Validator configurations:

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.

Properties:

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.

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. 

Logging form data

To log data sent in the contact form:

1. In the Form component, check the Track mail checkbox on the Submit settings tab.
2. Enable the trackEmail form processor.
3. Submit a form.
4. To view the log:
   
   • Go to Tools > Log Viewer. Select magnolia-form.log and click View. OR
   • Open /webapps/<webappName>/logs/magnolia-form.log on the file system.