Installation Guide

Prerequisites

• Magnolia CMS 6.4 or higher
• Java 17 or higher
• Maven 3.6 or higher

1. Add Maven Dependency

Easy Forms is available on Maven Central. Add the following dependency to your Magnolia webapp's pom.xml:

<dependency>
    <groupId>work.noice</groupId>
    <artifactId>easyforms</artifactId>
    <version>1.1</version>
</dependency>

2. Verify Maven Central Access

Maven Central is included by default in all Maven installations. If your project uses a private repository manager (Nexus, Artifactory), ensure it proxies Maven Central. You can verify the artifact is resolvable:

mvn dependency:resolve -Dartifact=work.noice:easyforms:1.1

3. Start Magnolia

Start (or restart) Magnolia. The module will be automatically installed and registered. You can verify the installation in AdminCentral under Modules.

The module creates the easyforms workspace and registers all form templates, dialogs, and REST endpoints automatically.

4. Creating Your First Form

1. Open the Pages app in Magnolia AdminCentral
2. Create a new page and select the EasyForms template
3. Configure form properties in the page dialog:
   • Form Name & ID — Unique identifier for the form
   • Submission Type — Email, database, or both
   • Email Recipients — Fixed address or dynamic routing
   • Success/Error Messages — Customize user feedback
4. Open the page editor and add form components:
   • Add a Container as the root form wrapper
   • Add Rows for multi-column layouts (up to 3 columns)
   • Drop Text, Options, File Upload, and other components into columns
   • Add a Button component for form submission
5. Publish the page and your form is live

Available Form Components

5. Global Configuration

Access the EasyForms configuration app in Magnolia AdminCentral to set up optional integrations:

Database Storage

Store submissions in PostgreSQL, MySQL, or H2. Tables are created automatically on first use.

# Example database configuration
URL:      jdbc:postgresql://localhost:5432/magnolia
Username: magnolia
Password: ********
Driver:   org.postgresql.Driver

S3 File Storage

Configure S3 or S3-compatible storage (MinIO) for file uploads. Set bucket, region, credentials, and optional custom endpoint.

# Example S3 configuration
Bucket:           my-form-uploads
Region:           ap-southeast-2
Access Key:       AKIA...
Secret Key:       ********
Endpoint:         (leave empty for AWS S3)
Path Style:       false (set true for MinIO)
Max File Size:    10485760 (10MB)
Allowed Types:    image/jpeg,image/png,application/pdf

reCAPTCHA v3

Add your reCAPTCHA v3 site key and secret key from the Google reCAPTCHA Admin Console. Enable per-form in the form page dialog.

Mailchimp

Configure your Mailchimp API key, audience ID, and data center. Supports merge field mapping from form data and double opt-in for GDPR compliance.

6. Email Configuration

Easy Forms uses Magnolia's built-in Mail module for sending email notifications. Ensure your Magnolia instance has SMTP configured.

• Static routing — Always send to a fixed email address
• Dynamic routing — Route to different addresses based on a form field value (e.g., a department dropdown where each option value is an email address)

Emails are sent as HTML with a professional template including form field values, file upload links, and submission metadata.

7. REST API

All endpoints are available under /.rest/easyforms/

Building from Source

git clone https://github.com/noicework/easyforms.git
cd easyforms
mvn clean install

The built JAR will be in target/easyforms-1.1.jar