Form module

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 .

Download

The Form module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository

Installing

Form is a Community Edition module. It is typically already installed. Launch the Configuration app and go to /modules/form to check.

Uninstalling

Configuration

The Form module is configured at /modules/form.

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

1. Create a new page based on a form template. STK ships with two sample templates: Form sends the collected data to an email address you specify. Public Users Management is a collection of forms for registering, authenticating and updating public users. See Public User Registration module for more.
2. Open the page and configure the form settings. Form settings define the title and name of the form and where the collected information should be submitted. Have a look at the the example contact configuration on the /demo-project/service/contact page.
   

3. Add a field set component to the form.
   

   Note that 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.
4. Add a field set.
   
5. Add fields inside the field set.
   

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

1. Create a new page based on the Form template. 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.
2. Create sub pages based on the Form Step template for the subsequent steps of the form.
   
   1. Add field sets and fields on the substep forms.

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:

Fields

See Form module components for fields that you can add into a field set.

Field validation

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 10485760
    
  • allowedMimeTypes: "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 requirements

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

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:

• 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.  
• 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 its value to true.
• TrackEmailProcessor  writes the content of the submitted form to 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.

Creating a custom form processor

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.

For more examples see Form processors in the PUR module.

Form components

The form components are configured in /modules/form/templates/components.  Form components are standard Magnolia components configured in the same way as all components.

Logging

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.

Disabling cache

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.