Form Developer Docs

Forms are centrally managed submission models embedded into FaceFlow Pages and Components.

They allow technical teams to define reusable inquiry and intake workflows that can be rendered in a cache-safe way, processed at submission time, and managed as structured business assets.

Core Responsibility

A Form is responsible for:

• reusable form definitions
• field schema
• runtime rendering
• validation and submission handling
• notification routing
• entry capture
• reuse across multiple Pages or Components

A Form should model one business workflow clearly. If one definition tries to handle several unrelated workflows, both operations and reporting become weaker.

Core Form Model

A Form usually combines:

• a stable form identity
• a field schema
• presentation configuration
• success and notification behavior
• submission handling rules
• entry storage and management

In practice, the Form layer defines both what the visitor can submit and how the business receives and processes that submission.

Conceptually:

{
  "name": "enterprise-demo-request",
  "fields": [
    { "name": "full_name", "type": "text", "required": true },
    { "name": "work_email", "type": "email", "required": true },
    { "name": "company", "type": "text", "required": true },
    { "name": "message", "type": "textarea", "required": false }
  ],
  "settings": {
    "submitText": "Request demo",
    "successMessage": "Thanks. Our team will contact you shortly."
  }
}

Supported Field Types

Supported field types include:

• text
• email
• phone
• url
• textarea
• number
• select
• radio
• checkbox
• checkboxes
• date
• file
• hidden

Field sets should stay aligned with the operational workflow. A Form that collects data the business does not use creates friction for both visitors and internal teams.

Form Definition Example

A technical review should be able to reason about the model quickly:

{
  "name": "contact-sales",
  "fields": [
    { "name": "full_name", "type": "text", "required": true },
    { "name": "work_email", "type": "email", "required": true },
    { "name": "company", "type": "text", "required": true },
    { "name": "team_size", "type": "select", "required": false }
  ],
  "settings": {
    "submitText": "Contact sales",
    "successMessage": "Thank you. We will reply shortly."
  }
}

This makes it possible to discuss field contract, required data, and workflow ownership before the Form is embedded anywhere.

Runtime Embedding

Forms are typically embedded into page sections through Components.

A common embed marker is:

<div data-form-embed="contact-form"></div>

Example section:

<section class="contact-section">
  <div class="section-copy">
    <h2>Talk to our team</h2>
    <p>Tell us about your goals and timeline.</p>
  </div>

  <div data-form-embed="enterprise-demo-request"></div>
</section>

This allows the page structure to remain reusable while the actual form model stays centrally managed.

Fixed vs Field-Backed Embeds

There are two common embed patterns.

Use a fixed managed form id when the template should always render one specific Form:

<div data-form-embed="enterprise-demo-request"></div>

Use a field-backed embed when a Component exposes a formSelect field and authors should choose the managed Form at authoring time:

<div data-form-embed="{contactForm}"></div>

Decision rule:

• fixed embed -> one stable workflow owned by the template
• field-backed embed -> reusable Component with author-selectable workflow

Submission Flow

At a high level:

1. the Form is defined centrally
2. it is embedded into a Page through a Component
3. the visitor submits structured input
4. validation and submission handling run
5. the submission is stored and routed to the relevant business workflow

Conceptually:

Component render
  -> runtime form HTML
  -> visitor submits
  -> validation
  -> entry saved
  -> notification routed
  -> success response returned

Integration Pattern

The clean integration path is:

Form definition
-> Component embed via formSelect or explicit data-form-embed marker
-> Page composition
-> runtime rendering and submission handling

That keeps form behavior centralized while allowing Pages and Components to stay reusable.

Notifications and Entries

Forms are not only about front-end capture. They also support the operational side of submissions.

Typical capabilities include:

• notification routing
• submission entry management
• entry review
• export workflows

Technical teams should review the full operational path, not just whether the form visually renders on the page.

Field Contract Guidance

Keep the field contract narrow enough that the workflow stays obvious.

Typical patterns:

• contact or demo request -> text, email, textarea, optional select
• qualification flow -> text, email, select, number
• upload-assisted intake -> add file only when the business truly processes attachments

Prefer one clear workflow contract over one oversized form that tries to capture every possible lead path.

Reuse Strategy

Good Form design usually favors reuse.

If multiple Pages share the same business workflow, they should usually share the same Form model.

This improves:

• maintainability
• consistency of field contracts
• notification behavior
• reporting and downstream handling

Example:

Homepage demo CTA
Pricing page demo CTA
Enterprise solution page CTA
  -> same demo-request Form

If the workflow is the same, the Form should usually be the same.

Technical Guidance

• model each Form around one business workflow
• reuse one form definition across Pages where the workflow is the same
• keep field requirements aligned with actual operational needs
• avoid page-specific duplication when a shared model will work
• review rendering, submission, notification, and entry handling together
• test the real submission path before release

Anti-Patterns

Avoid:

• creating a new Form for every Page when the workflow is identical
• combining unrelated lead paths into one oversized Form
• collecting optional data the business never uses
• hard-coding form markup inside page templates instead of embedding the managed model
• reviewing visual output only and ignoring the operational path

Example Build Pattern

Component:
  lead-form

Embed:
  <div data-form-embed="contact-sales"></div>

Pages:
  /pricing/
  /enterprise/
  /contact/

That keeps one workflow consistent across several conversion surfaces.

Related

• Forms Product Overview
• Form Guide
• Components
• Pages
• Export and Import