Similar content

Loading

Powered by Canoo FindIT.

Form

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 such as contact and allows customization. Multiple form elements that belong together, such as 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 CMS core system. For information on working with components to create forms, see the reference section.

Download

Download the Form module from Magnolia Store or Nexus repository.

Installing

Form is a community module included in the Standard Templating Kit bundle, and typically already installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, please see the general module installation instructions. In order to use this module, the STK needs to be installed.

Uninstalling

See the general module uninstalling instructions and advice.

Mail configuration

The Form module uses the Mail module to send form data in email. Configure SMTP protocol to enable sending of mail.

Creating a form

  1. Create a new page.
  2. Assign a form template to the page. STK ships with two sample templates: Contact Form which sends the collected data to an email address you specify and Public Users Management which is a collection of forms for registering, authenticating and updating public users. Double-click the template column to select a template.
  3. Open the page and edit the form settings.
  4. Add a field set component on the form. You can have multiple field sets in the one form. This helps groups them visually, for example contact details in one set and feedback message in another.
  5. Add a field set.
  6. Add fields inside the field set.

Creating a multistep form

  1. Create a new page. This will be the master page (first step) of the process.
  2. Assign the Contact Form template to the page.
  3. Open the page.
    1. Edit the form settings.
    2. Add a field set component on the form.
    3. Add fields inside the field set.
  4. Create as many new pages under the master page as you have form steps.
  5. Assign the Contact Form Step template to the pages.
  6. Add field sets and fields on the substep forms.

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:

  • none. No validation is performed. Any value entered into the field is accepted.
  • email. Value needs to be a valid email address. Validity is checked with regular expression ^\S+@\S+$. This validator uses the ValidateExpression class which 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 which 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.
  • username. Verifies that the entered username does not exists in the system. The Java class for this validator is in the Public User Registration (PUR) module.
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.

Creating a custom regular expression validator

The easiest way to create a custom field validator is to use the ValidateExpression class and write a regular expression.

For example, to validate a U.S. ZIP code:

  1. Go to /modules/form/config/validators.
  2. Create a new content node zip under validators.
  3. Create two data nodes under zip:
    • class. Set the value to info.magnolia.module.form.validators.ValidateExpression.
    • expression. Set the value to ^\d{5}(-\d{4})?$. This regular expression validates ZIP codes of type ZIP+4.

Assign the validator to a field:

  1. Open a page that has a form, such as the Contact page at /demo-project/service/contact.
  2. Add a new text field on the form.
  3. Select zip from the Validation dropdown.
  4. Save.

Test the validation:

  1. Fill the ZIP code field with an invalid code such as 4321A.
  2. Fill other mandatory fields on the form.
  3. Submit.
The form tells you that the ZIP code was invalid and highlights the problematic field. This is the expected outcome.

Creating a custom validator class

To validate field values against an external source you need a custom Java class. Look at the API documentation:

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:

  • sendContactEmail 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. API
  • sendConfirmationEmail 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 data node under the processor and set its value to true. API
  • trackEmail 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 data node under the processor and set its value to true. API

Creating a custom form processor

The three example form processors above send the form data in email. If you need to store the data into a database or process it in another way, write your own form processor. See Storing form data in the Data module for an example.

Info

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.

See also these examples:

Logging

To log data sent in the contact form:

  1. In form settings, check the Track mail checkbox on the Submit settings tab.
  2. Create a new data node enabled under /modules/form/templates/components/form/formProcessors/trackEmail and set its value to true.
  3. Submit the form.
  4. To view the log:
    • Go to Tools > Log viewer. Select the magnolia-form.log and click View. OR
    • Open webapps/<webappName>/logs/magnolia-form.log on the file system.
For logging mail errors, see Mail > Error logging.

Disabling cache

Info

Disabling cache on form pages is only needed for Magnolia 4.4. In earlier and later versions disabling happens automatically.

Starting with Magnolia CMS 4.4, individual form pages and the first page of a multi-step form need to be excluded from cache to prevent "session expired" errors.

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/default/cachePolicy/voters/urls/excludes. The screenshot below shows the exclusion of the Contact page in demo-project and the first page of the multi-step form in demo-features.

Form settings

Form settings define the title and name of the form and where the collected information should be submitted. Settings are configured in the Form Settings dialog. You can access this dialog by clicking the Form Settings button on the green bar.

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".
Breadcrumb When checked will display a breadcrumb 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 magnolia-form.log file.

(!) Checking this box is not enough. You need to also add an enabled data node under the trackEMail form processor and set its value to true. See Form processors.

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 ${senderMail} if the email field is named senderMail. 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.
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 Type of message: HTML or plain text. With HTML you can use markup in the Text field.
Text Body of the email message. 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.

Confirmation email tab

Field Description
Send confirmation Sends a confirmation mail to the submitting user.

(!) Checking this box is not enough. You need to also add an enabled data node under the SendConfirmationEMailProcessor form processor and set its value to true. See Form processors.
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 ${senderMail}.
Subject Email subject line such as "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.
Type Type of message: HTML or plain text. With HTML you can use markup in the Text field.
Text Body of the email message. This can be a simply acknowledgement that data was submitted or you can summarize the collected data with Freemarker tags such as ${message}.

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:

  1. Click New Field Set in the green bar on the form.
  2. Enter a Title, a common nominator for the fields in this set such as "Address" or "Your message". The title is displayed above the fields.
  3. Check the Display marker for required fields check box if you want to display a required field marker, typically an asterisk, next to the field label.
  4. Click Save.

Fields

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

Example forms in demo-project

The demo-project and demo-features websites include examples of forms.

Contact form

Basic contact form that allows visitors to contact site staff about any topic. Consists of text fields and a submit button. Form settings are configured to send the collected data to a recipient in email.

Try it out:

User registration form

The Public User Registration (PUR) module is used to authenticate public users. It provides several forms out-of-the-box.

The User Registration Form creates a user profile in the Security repository. The form sends an email containing a verification link to the user. Once the user has verified the new account, they can log in.

Note that registered users are added to the security repository only on the public instance. You cannot see them on the author instance. If you test the form on the demo instance sign into AdminCentral on the public instance to see the new user account. Public instance u/p: superuser/superuser

Try it out:

Login form

Login form for public users. Once a user is registered they can log into the website. Users are authenticated against profiles in the security repository.

Try it out:

User profile update form

Contains the same fields as the registration form. An email notification is sent to the user after submission.

Try it out:

Password retrieval form

Allows a user to retrieve a forgotten password. The password is sent in email to the address registered in the user profile.

Try it out:

Logout form

Allows a logged-in user to log out. Typically this form contains just a single Logout button. There is no ready-made example of this form in demo-project. The logout feature is implemented with a Login/Logout link component instead.

To see the Logout form in action, do this on the author instance:

  1. Create a new page in /demo-project/members-area. Assign the Public Users Management template to the page.
  2. Add a new Logout form component on the page.
  3. Add a new field set in the form.
  4. Add a new submit button on the form. Label it "Logout".
  5. Add a new hidden field on the form. Set field name to mgnlLogout and value to true.
  6. Activate the page to public instance.
Do this on the public instance:
  1. Create a new public user in /demo-project/members-area/registration.
  2. Verify the account with the link sent to your email address.
  3. Log in using the new user account in /demo-project/members-area/login
  4. Navigate to your custom logout page and click the Logout button.

Members area

Adds a component that is displayed only to logged-in users. This can be used to create content that is intended for authenticated users only, such as an extranet where you provide downloads for clients and customers.

Try it out:

Multi-step form

Splitting a large form into multiple steps allows the visitor to focus on one step at a time while none of the provided data will be lost when going back.

To create a multi-step form, create the first page of the form process first. Add the subsequent steps as sub-pages under the main page. Apply the page Contact Form Step template to the substeps. The substeps will be detected by Magnolia CMS automatically.

Visitors can move forward and backwards between steps without losing already entered data. Each step will be evaluated individually. The form module also allows them to upload files but the upload field works only on the last step of the process. A pluggable model allows you to dynamically select a next step based on custom business logic if so desired.

The demo-features website includes an example call for conference papers.

Try it out: