Ontwikkelaarsdocumentatie voor formulieren

Formulieren zijn centraal beheerde inzendingsmodellen die worden ingebed in FaceFlow-pagina's en componenten.

Ze stellen technische teams in staat herbruikbare aanvraag- en intakeworkflows te definiëren die cache-veilig gerenderd kunnen worden, bij inzending verwerkt worden en als gestructureerde zakelijke assets beheerd kunnen worden.

Kernverantwoordelijkheid

Een formulier is verantwoordelijk voor:

• herbruikbare formulierdefinities
• veldenschema
• runtime-rendering
• validatie- en inzendafhandeling
• routering van meldingen
• vastlegging van inzendingen
• hergebruik over meerdere pagina's of componenten

Een formulier moet één zakelijke workflow duidelijk modelleren. Als één definitie probeert meerdere niet-gerelateerde workflows af te handelen, verzwakken zowel de operatie als de rapportage.

Kernformuliermodel

Een formulier combineert gewoonlijk:

• een stabiele formulieridentiteit
• een veldenschema
• presentatieconfiguratie
• gedrag bij succes en meldingen
• regels voor afhandeling van inzendingen
• opslag en beheer van inzendingen

In de praktijk definieert de formulierenlaag zowel wat de bezoeker kan indienen als hoe het bedrijf die inzending ontvangt en verwerkt.

Conceptueel:

{
  "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."
  }
}

Ondersteunde veldtypen

Ondersteunde veldtypen zijn onder andere:

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

Veldensets moeten in lijn blijven met de operationele workflow. Een formulier dat gegevens verzamelt die het bedrijf niet gebruikt, creëert frictie voor zowel bezoekers als interne teams.

Voorbeeld formulierdefinitie

Een technische beoordeling moet snel inzicht kunnen krijgen in het model:

{
  "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."
  }
}

Dit maakt het mogelijk om veldcontracten, vereiste gegevens en workflow-eigendom te bespreken voordat het formulier ergens wordt ingebed.

Inbedding tijdens runtime

Formulieren worden doorgaans via componenten in paginasecties ingebed.

Een veelgebruikt embedmarker is:

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

Voorbeeldsectie:

<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>

Dit maakt het mogelijk dat de paginastructuur herbruikbaar blijft terwijl het daadwerkelijke formuliermodel centraal beheerd wordt.

Vaste versus veld-ondersteunde inbeddingen

Er zijn twee veelvoorkomende inbedpatronen.

Gebruik een vaste beheerde formulier-id wanneer de template altijd één specifiek formulier moet renderen:

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

Gebruik een veld-ondersteunde inbedding wanneer een component een formSelect-veld blootlegt en auteurs het beheerde formulier tijdens het aanmaken moeten kunnen kiezen:

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

Beslissingsregel:

• vaste inbedding -> één stabiele workflow die eigendom is van de template
• veld-ondersteunde inbedding -> herbruikbare component met door de auteur selecteerbare workflow

Inzendingsstroom

In hoofdlijnen:

1. het formulier wordt centraal gedefinieerd
2. het wordt via een component in een pagina ingebed
3. de bezoeker dient gestructureerde input in
4. validatie en inzendafhandeling worden uitgevoerd
5. de inzending wordt opgeslagen en gerouteerd naar de relevante zakelijke workflow

Conceptueel:

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

Integratiepatroon

Het duidelijke integratiepad is:

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

Dat houdt het formuliergedrag gecentraliseerd terwijl pagina's en componenten herbruikbaar blijven.

Meldingen en inzendingen

Formulieren gaan niet alleen over frontendvastlegging. Ze ondersteunen ook de operationele kant van inzendingen.

Typische mogelijkheden zijn onder andere:

• routering van meldingen
• beheer van inzendingen
• beoordeling van inzendingen
• exportworkflows

Technische teams moeten het volledige operationele pad beoordelen, niet alleen of het formulier visueel op de pagina wordt weergegeven.

Richtlijnen voor veldcontract

Houd het veldcontract smal genoeg zodat de workflow duidelijk blijft.

Typische patronen:

• contact- of demo-aanvraag -> text, email, textarea, optioneel select
• kwalificatieflow -> text, email, select, number
• intake met uploadondersteuning -> voeg file alleen toe wanneer het bedrijf daadwerkelijk bijlagen verwerkt

Geef de voorkeur aan één duidelijk workflowcontract boven één opgeblazen formulier dat probeert elk mogelijk leadpad vast te leggen.

Hergebruikstrategie

Goed formulierontwerp geeft doorgaans de voorkeur aan hergebruik.

Als meerdere pagina's dezelfde bedrijfsworkflow delen, moeten ze doorgaans hetzelfde formuliermodel gebruiken.

Dit verbetert:

• onderhoudbaarheid
• consistentie van veldcontracten
• gedrag van meldingen
• rapportage en downstream-afhandeling

Voorbeeld:

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

Als de workflow hetzelfde is, zou het formulier meestal hetzelfde moeten zijn.

Technische richtlijnen

• modelleer elk formulier rond één zakelijke workflow
• hergebruik één formulierdefinitie op meerdere pagina's wanneer de workflow hetzelfde is
• houd veldvereisten in lijn met daadwerkelijke operationele behoeften
• vermijd pagina-specifieke duplicatie wanneer een gedeeld model volstaat
• beoordeel rendering, inzending, melding en inzendafhandeling samen
• test het echte inzendpad vóór release

Anti-patronen

Vermijd:

• voor elke pagina een nieuw formulier aanmaken wanneer de workflow identiek is
• niet-verwante leadpaden combineren in één opgeblazen formulier
• optionele gegevens verzamelen die het bedrijf nooit gebruikt
• formuliermarkup hardcoderen in paginatemplates in plaats van het beheerde model te embedden
• alleen de visuele output beoordelen en het operationele pad negeren

Voorbeeld bouwpatroon

Component:
  lead-form

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

Pages:
  /pricing/
  /enterprise/
  /contact/

Dat houdt één workflow consistent over meerdere conversiepunten.

Gerelateerd

• Overzicht van het Forms-product
• Formuliergids
• Componenten
• Pagina's
• Exporteren en importeren