Docs 1
Home GitHub
menu_book Navigation menu
Documentation Front-end Form Builder

Form Builder

Pragma CMS includes a highly advanced, drag-and-drop Form Builder. It allows administrators to create complex forms (Contact, Surveys, Lead Generation) without writing a single line of code, while providing developers with powerful hooks for third-party integrations.

Form Configuration & Routing

When creating a form, you have granular control over what happens after a user submits it:

Submit Actions & Redirects

Instead of just showing a basic success message, you can dynamically route users:

  • Message: Displays a rich-text success message (parsed via Summernote).
  • Redirect to a Collection Entry: Automatically redirects to a specific article, product, or dynamic page. If the entry's slug changes, the redirect updates automatically.
  • Redirect to a System Page: Redirects to a fixed route (e.g., /blog, /contact).
  • Custom URL: Redirects to an external website.

Conditional Email Routing

Instead of sending all submissions to a single admin email, Pragma CMS allows Conditional Routing. You can route emails to different addresses based on what the user selected in the form.

User Notifications (Auto-responders)

You can easily enable and customize a confirmation email (Subject and Body) that will automatically be sent to the user who filled out the form (provided the form contains an email field).

Field Builder & Validation

The drag-and-drop interface supports a wide variety of fields, from simple text inputs to complex Composite fields (repeater logic) and HTML separators.

Advanced Field Features:

  • Validation Rules: Natively enforce data types (Email, Numeric, Alpha, URL), string lengths (min, max), or apply Custom Regex directly from the UI.
  • Conditional Logic: Show or hide fields dynamically based on the user's previous answers. (e.g., Show field "Company Name" IF "Are you a professional?" EQUALS "Yes"). Supported operators include: equals, not_equals, contains, starts_with, greater_than, less_than.

Displaying a Form

Pragma CMS provides two ways to display a built form on the front-end:

1. No-Code Method (Page Builder)

Recommended for content editors:

  1. Go to Pages.
  2. Edit a page using the Builder content type.
  3. Add a new block, select Form, and choose your form from the dropdown.

2. Developer Method (Templates)

For custom Twig templates or PHP views, you can inject a form using its unique handle. The core takes care of the CSRF tokens and required HTML markup.

In Twig:

TEXT 
{{ renderForm('YOUR_FORM_HANDLE', {'ajax': true}) }}

In PHP:

PHP 
<?= FormManager::renderForm('YOUR_FORM_HANDLE', ["ajax" => true]); ?>

The Magic of the Built-in Form Handler

When you render a form using the CMS, it automatically leverages the built-in JavaScript form handler (activated via the data-cms-form="true" attribute). This lightweight, dependency-free script handles everything a modern form needs:

  • Zero-Config AJAX (data-ajax="true"): Submits the form asynchronously without reloading the page. It automatically displays a loading spinner and handles server responses natively.
  • Real-Time Conditional Logic: It parses the data-conditional-logic attributes injected by the PHP backend and instantly shows/hides fields based on user input (e.g., Show "Company Name" IF "Professional" is Checked). It safely toggles the required attributes on the fly.
  • Advanced File Handling: Automatically creates visual previews for uploaded images (.file-previews), enforces file size limits (data-max-size), checks allowed MIME types, and prevents duplicates.
  • Native Recaptcha v3: If enabled in the form settings, the script automatically negotiates the Google reCAPTCHA v3 token before submission.
  • Accessibility First (WCAG): Fully integrates ARIA live regions (aria-live="polite", aria-describedby) for screen readers. Validation errors are announced dynamically without disrupting the user flow.

Managing Submissions

All form submissions are securely stored in the database.

From the Admin panel, you can:

  • View the submitted data (JSON decoded natively).
  • Download attached files (securely linked to the submission).
  • See the exact submission date and status (Read/Unread).
  • Direct Reply: If the submission contains an email, the UI provides a quick "Reply" button that triggers a mailto: link with the form's subject.

Developer API: Frontend Events

While the built-in form handler manages the core logic, it exposes custom JavaScript events that allow developers to hook into the submission lifecycle. This makes it easy to integrate analytics, custom animations, or third-party tracking scripts.

JAVASCRIPT 
// Fired right before the AJAX request is sent.
// You can modify the FormData object here if needed.
document.addEventListener('cms:form:submitted', (e) => {
const { form, formData }=e.detail;
console.log(`Form${form.id} is submitting...`);
});

// Fired when the server returns a successful response.
document.addEventListener('cms:form:success', (e) => {
const { form, result }=e.detail;

// Example: Trigger analytics event
if (typeoffbq!=='undefined') {
fbq('track','Lead');
    }
});

// Fired when the server returns validation or processing errors.
document.addEventListener('cms:form:error', (e) => {
const { form, error, result }=e.detail;
console.error('Form failed to submit:',error);
});