Form templates (DNN)

Don't start from a blank canvas. The Template Gallery ships ready-made forms — from a 4-field contact form to a 27-field patient intake — and any MegaForm JSON export can be imported as a starting point.

Where it lives

The gallery opens from the Form Wizard's Setup step (Template Gallery — browse the full library), with quick picks right on the step: Blank Form, Contact Form, Leave Request, Support Ticket, Feedback Survey — plus the premium set (EuroYouth application, Wellness & Patient Intake, Vendor Application, Tabbed Account Setup, Project Intake & Onboarding, …).

Using it

• Filter by category chips — Event-registration, Health, Application, Business, Travel, Authentication, Contact, Reports, Healthcare… — or search by name.
• Pick a card and the wizard continues with that template's fields, layout, theme and (where the template carries one) its workflow — everything stays editable in the builder afterwards.
• Import JSON — upload (or paste) a MegaForm export. Exports are cross-platform: a form exported from an Oqtane site imports on DNN unchanged, which is also the practical way to move forms between environments.

Templates are starting points, not locks — after import the form is yours: rename it, add fields, restyle it, attach a different workflow.

Form Builder (DNN)

The builder is MegaForm's full designer — a fullscreen canvas with a field palette on the left, the live form in the middle, and per-field/per-form panels on the right. On DNN it opens from the admin toolbar's Form Builder, from any form's row on the dashboard, or straight after the wizard creates a form.

The layout

Draft → Publish

Every edit saves into the form's Draft; the public page keeps serving the last published version until you hit Publish. That means you can rework a live form safely — the wizard's output starts as a Draft too.

The builder UI is the same engine across DNN, Oqtane and the standalone host — a form designed here exports/imports unchanged anywhere MegaForm runs.

Controls & widgets (DNN)

Beyond the basic inputs, the palette's Widgets group holds MegaForm's advanced controls — payments, data grids that read your SQL tables live, appointment pickers, calculators, geolocation and more. Same click-to-add as any field.

What's in the box

…plus composite presets (Address, Date Range, Money/Amount, Measurement, Price Range) in the Layout group.

Each widget carries its own properties panel — data-driven ones take a connection + query (Storage & Integrations); interactive ones expose their options directly. Widgets render identically in the DNN page and in the standalone/embedded hosts, and the widget JS ships as separate per-widget bundles so a form only loads what it uses.

Drag & drop layout (DNN)

Forms aren't single columns. The palette's Layout group builds structure — rows with columns, a 12-column flex grid, section breaks, HTML blocks — and every field on the canvas can be dragged into place by its handle.

The Layout group

Moving things

• Reorder — grab a field's ⠿ handle and drag it above/below any other field; a drop indicator tracks the target as you move.
• Into columns — drag a field into a row's column; drag it back out to leave.
• Click-to-add places new palette items at the end — drag afterwards to position, or select a field first and the next added item lands after it.

Multi-step forms add another level: the wizard's multi-step toggle (or the builder's step bar) splits the canvas into pages with their own progress indicator — layout works the same within each step.

MegaForm template contract, version 1

One template format is used by the Wizard, Builder, previews and public renderer on DNN (ASCX and MVC), Umbraco and Oqtane. A new design must be supplied as template data. It must not require a branch in the Wizard keyed by its title, slug, category or CSS prefix.

Layout is flexible; bindings are shared

Templates can use unrelated layouts: an editorial split panel, a compact card, a dark event page, a soft illustration, or native multi-page sections. Keep each design's HTML structure, CSS classes, pictures and responsive rules. The contract standardizes the connection to the form engine, not its appearance.

Set settings.templateContractVersion to 1. Older templates use the generic compatibility reader; their titles never select special Wizard behavior.

Stable layout hooks

Use data-mf-field="email" on the element that owns one field's caption, input token and help. Use data-mf-fields on its parent insertion zone. These attributes have no visual styling: choose any tags, class names, grid, colors or artwork. They let the editor add, clone and remove a field without guessing your design's class names. Keep headings, images, page navigation and submit buttons outside a field wrapper.

<div class="studio-fields" data-mf-fields>
  <div class="studio-field" data-mf-field="email">
    {{field:email}}
  </div>
</div>

For a separately positioned caption, place {{label:email}}, {{required:email}} and {{help:email}} inside that field wrapper and configure the native field to avoid duplicate visible labels. A wrapper must contain exactly its own field token. Row/FlexGrid wrappers own the layout field token; their children stay in the schema. A new field copies a neighboring field wrapper and rebinds its metadata; an empty zone receives a native field wrapper. No new Wizard code is needed for a different design.

Blocks: headings and fields move together

Wrap each logical group in an element with a unique data-mf-block="contact-details". Include its heading, introductory text, grid, field wrappers and related decoration inside the block. Keep the form hero, shared navigation and submit actions outside it. Blocks are independent siblings; use Row/FlexGrid or composite fields for nesting inside a block.

<section class="studio-section" data-mf-block="contact-details">
  <h2>{{content:contact_heading}}</h2>
  <p>{{content:contact_intro}}</p>
  <div class="studio-grid" data-mf-fields>
    <div data-mf-field="email">{{field:email}}</div>
    <div data-mf-field="phone">{{field:phone}}</div>
  </div>
</section>

In Wizard → Fields, Blocks & fields shows each group with its fields. Use the up/down buttons to move the whole block among siblings in the same layout container. Delete … block removes its heading, supporting text and all fields together, including nested Row/composite/widget configuration. Undo block change restores the last block operation in the current draft. No saved form changes until Create succeeds.

Undo is available immediately after a block operation; making another field edit starts a new draft action and clears that block undo, so it cannot overwrite a later field change.

Deleting the last field of a block removes the entire empty group immediately in the design preview and in the saved form. An explicitly informational block with no original fields is retained. A block cannot cross an unrelated sidebar or page boundary; native multi-page steps retain their own page headings and navigation.

For an existing sibling layout that cannot gain a new DOM wrapper without changing CSS, range comments express the same ownership:

<!--mf:blocks:v1-->
<!--mf:block:contact-details-->
<h2>Contact details</h2>
<div>{{field:email}}</div>
<div>{{field:phone}}</div>
<!--/mf:block:contact-details-->

The marker records that block discovery is complete, so deletion does not reinterpret surrounding artwork as a new group. Legacy templates use generic heading/section and repeated separator discovery. New designs should declare ownership explicitly rather than depend on that compatibility inference. There are no rules keyed to a template's name, slug or CSS prefix.

Supported bindings

Field and content text is encoded, not executable HTML. Layout belongs in customHtml. Prefer the label already emitted by {{field:key}}; use the metadata tokens only when the design needs its caption elsewhere, and avoid rendering two visible labels. Field keys are stable identifiers; use labels for user-facing wording. Changes to a key must also update any authored CSS selectors or custom script references to that key.

Minimal example

{
  "id": "studio-contact",
  "slug": "studio-contact",
  "title": "Studio contact",
  "fields": [
    { "key": "email", "type": "Email", "label": "Your email", "required": true },
    { "key": "message", "type": "Textarea", "label": "Tell us about your project" }
  ],
  "settings": {
    "templateContractVersion": 1,
    "customHtml": "<section class='studio-contact'><aside><h1>{{form:title}}</h1><p>{{content:intro}}</p></aside><div><div class='studio-contact-fields' data-mf-fields><div data-mf-field='email'>{{field:email}}</div><div data-mf-field='message'>{{field:message}}</div></div><button type='submit'>{{form:submit}}</button></div></section>",
    "customCss": ".studio-contact{display:grid;grid-template-columns:1fr 2fr;gap:2rem;max-width:100%;color:#183d34;background:#fff}.studio-contact-fields{min-width:0}.studio-contact .mf-input{max-width:100%}@media(max-width:700px){.studio-contact{grid-template-columns:1fr}}",
    "customContent": { "intro": "We would love to hear what you are working on." }
  },
  "submitButtonText": "Send enquiry"
}

Replace the layout and CSS to create a completely different design. Keep the schema and binding rules. Adding an Address composite or Signature widget means adding its schema entry and a field token; it does not require template-specific Wizard code.

Embedding and interaction rules

• MegaForm supplies the outer form. Do not nest a second <form> or hard-code an input with its own name.
• Place each native field token once. A Row or FlexGrid token owns its children; do not also render its children separately.
• Use a unique template root class. Do not style body, html, :root, host navigation or sibling modules. Avoid viewport-width elements, fixed page overlays and negative offsets that leave the module pane.
• Use container-relative sizing, min-width:0 for grid/flex children, responsive images and a narrow-pane layout. The module may be embedded next to another form or inside a theme column.
• Prefer schema Section page breaks and native widgets over custom navigation or input implementations. Managed scripts must initialize within their supplied form root and tolerate repeated mounts.
• Keep data connections, table mapping and submit workflows separate from design. A downloaded template does not silently grant SQL writes; the Wizard asks the author to choose a data source.

Authoring and QA

The Wizard can edit field properties and template wording, then preview the resulting design at desktop, tablet and mobile widths. Its design preview is a snapshot; public submit, conditional logic and interactive widgets must also be exercised after creation.

From MegaForm.UI, run:

node scripts/check-template-contract.cjs
node scripts/test-wizard.cjs

The contract checker reports missing field/content bindings, duplicate keys, hard-coded controls, nested forms, inline event scripts and CSS that escapes the pane. Version 1 violations fail the build. Legacy records are reported separately rather than silently rewritten by the checker.

The published source catalog contains 82 version 1 templates. upgrade-template-contract.cjs is an explicit, repeatable migration tool: it binds recognized legacy field captions, extracts editable text, annotates identifiable field-only wrappers and verifies equivalent resolved HTML (apart from those editor attributes) before writing the entire batch. It does not rewrite CSS or scripts. Historical/archive templates remain readable through the compatibility path.

upgrade-template-blocks.cjs annotates structurally identifiable field groups across that source catalog and verifies identical markup after removing editor hooks. It preserves CSS, assets and scripts. Templates with one uninterrupted field stack or static content do not acquire invented section headings. Test deletion of a whole group, deletion of its final field, block reorder, undo and the resulting saved public form whenever a design changes.

For every design, verify: unchanged save preserves artwork; edited labels/options/required rules persist; adding/removing a field leaves no empty caption/card; text edits affect only their intended content; desktop/mobile previews match the saved form; two modules do not alter each other's styles; composite values, files and signatures survive a real submission. Keep a screenshot comparison for designs with special positioning or responsive artwork.

Field permissions (DNN)

A form doesn't have to look the same for everyone. Per field, you decide who can see it and who can see but not edit it — using the DNN roles your portal already has. Rules are applied server-side when the form is delivered: a hidden field never even reaches the browser.

Per-field rules

1. Select a field on the canvas and open the Access tab (right panel).
2. Under Field visibility by role:
   • Visible to — tick the roles that may see the field; untick everything and it's visible to everyone (the default).
   • Read-only for — tick roles that may see the field but not change it.
3. Save. The rules ride inside the form schema and are enforced when the schema is served — the JSON each user downloads is projected for that user, so a field they may not see is stripped before it leaves the server. Anonymous or unresolvable callers always get the most-restricted projection.

The permission matrix

Above the per-field rules, the same Access tab holds the form-level Permissions & Access matrix — role/user rows (All Users, Anonymous Users, Authenticated Users, plus every portal role) against form actions (submitting, reading records, inbox access, approvals). The matrix is canonical shared data across DNN, Oqtane and Web — granting a role here means the same thing on every host. Expand shows all columns; Save Access Rules persists it.

Roles are the host's roles — on DNN that's your portal's role list (the recording shows this site's own: Administrators, Content Editors, Content Managers, Finance, Operations…). Create roles in DNN's admin as usual; MegaForm picks them up automatically.

Module settings & theme (DNN)

Settings on the admin toolbar opens the module's configuration popup — three tabs that control what this page shows and how it looks, without touching the form itself.

The current recording below shows Form Settings → Appearance in the builder. Module-level overrides described in this article are a separate DNN module configuration.

The three tabs

Save module settings applies to THIS module instance — the same form on another page can look completely different.

Theme layers

Styling is layered, most-specific wins:

1. Form theme — designed with the form in the builder's Design tab / Theme Designer.
2. Module Theme & Layout (this popup) — per-page overrides: presets + layout + typography.
3. Update Theme (toolbar button) — re-syncs the module's cached style from the form's current theme after you restyle the form.

Presets here are the same set as the Theme Designer's, so a page override and a form-level design stay visually consistent.