Documentazione per sviluppatori sui Moduli

I moduli sono modelli di invio gestiti centralmente incorporati nelle Pagine e nei Componenti di FaceFlow.

Consentono ai team tecnici di definire flussi di richiesta e raccolta riutilizzabili che possono essere renderizzati in modo sicuro per la cache, elaborati al momento dell'invio e gestiti come risorse aziendali strutturate.

Responsabilità principali

Un modulo è responsabile di:

• definizioni di modulo riutilizzabili
• schema dei campi
• rendering a runtime
• validazione e gestione degli invii
• instradamento delle notifiche
• acquisizione delle voci
• riutilizzo attraverso più Pagine o Componenti

Un modulo dovrebbe modellare chiaramente un singolo flusso di lavoro aziendale. Se una definizione cerca di gestire diversi flussi non correlati, sia le operazioni che il reporting ne risentono.

Modello principale del modulo

Un modulo di solito combina:

• un'identità del modulo stabile
• uno schema dei campi
• configurazione di presentazione
• comportamento di successo e notifiche
• regole di gestione degli invii
• memorizzazione e gestione delle voci

In pratica, il livello del modulo definisce sia cosa il visitatore può inviare sia come l'azienda riceve ed elabora quell'invio.

Concettualmente:

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

Tipi di campo supportati

I tipi di campo supportati includono:

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

Gli insiemi di campi dovrebbero rimanere allineati con il flusso operativo. Un modulo che raccoglie dati che l'azienda non utilizza crea attrito sia per i visitatori che per i team interni.

Esempio di definizione del modulo

Una revisione tecnica dovrebbe essere in grado di ragionare rapidamente sul modello:

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

Questo rende possibile discutere il contratto dei campi, i dati richiesti e la proprietà del flusso di lavoro prima che il modulo venga incorporato da qualche parte.

Incorporazione a runtime

I moduli sono tipicamente incorporati in sezioni di pagina tramite Componenti.

Un marcatore di incorporazione comune è:

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

Esempio di sezione:

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

Questo permette alla struttura della pagina di rimanere riutilizzabile mentre il modello effettivo del modulo rimane gestito centralmente.

Incorporazioni fisse vs incorporazioni basate su campi

Ci sono due schemi di incorporazione comuni.

Usa un id di modulo gestito e fisso quando il template dovrebbe sempre renderizzare uno specifico Modulo:

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

Usa un'incorporazione basata su campo quando un Componente espone un campo formSelect e gli autori dovrebbero scegliere il Modulo gestito al momento della creazione:

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

Regola decisionale:

• incorporazione fissa -> un flusso di lavoro stabile posseduto dal template
• incorporazione basata su campo -> Componente riutilizzabile con flusso selezionabile dall'autore

Flusso di invio

Ad alto livello:

1. il modulo è definito centralmente
2. viene incorporato in una Pagina tramite un Componente
3. il visitatore invia input strutturato
4. vengono eseguite la validazione e la gestione dell'invio
5. l'invio viene memorizzato e instradato verso il flusso aziendale pertinente

Concettualmente:

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

Schema di integrazione

Il percorso di integrazione pulito è:

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

Questo mantiene il comportamento del modulo centralizzato permettendo a Pagine e Componenti di rimanere riutilizzabili.

Notifiche e inserimenti

I moduli non riguardano solo la cattura front-end. Supportano anche il lato operativo degli invii.

Le capacità tipiche includono:

• instradamento delle notifiche
• gestione delle voci di invio
• revisione delle voci
• flussi di esportazione

I team tecnici dovrebbero rivedere l'intero percorso operativo, non solo se il modulo viene visualizzato sulla pagina.

Indicazioni sul contratto dei campi

Mantieni il contratto dei campi sufficientemente circoscritto in modo che il flusso di lavoro rimanga ovvio.

Pattern tipici:

• contatto o richiesta demo -> text, email, textarea, select opzionale
• flusso di qualificazione -> text, email, select, number
• raccolta assistita con upload -> aggiungi file solo quando l'azienda elabora davvero gli allegati

Preferisci un contratto di flusso chiaro piuttosto che un modulo sovradimensionato che cerca di catturare ogni possibile percorso di lead.

Strategia di riutilizzo

Un buon design dei moduli di solito favorisce il riutilizzo.

Se più Pagine condividono lo stesso flusso aziendale, dovrebbero di solito condividere lo stesso modello di Modulo.

Questo migliora:

• manutenibilità
• coerenza dei contratti dei campi
• comportamento delle notifiche
• reporting e gestione a valle

Esempio:

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

Se il flusso è lo stesso, di solito il Modulo dovrebbe essere lo stesso.

Indicazioni tecniche

• modella ogni Modulo attorno a un singolo flusso di lavoro aziendale
• riutilizza una definizione di modulo tra le Pagine quando il flusso è lo stesso
• mantieni i requisiti dei campi allineati con le reali esigenze operative
• evita duplicazioni specifiche della pagina quando un modello condiviso può funzionare
• rivedi insieme rendering, invio, notifiche e gestione delle voci
• testa il percorso reale di invio prima del rilascio

Pratiche da evitare

Evita di:

• creare un nuovo Modulo per ogni Pagina quando il flusso è identico
• combinare percorsi di lead non correlati in un unico Modulo sovradimensionato
• raccogliere dati opzionali che l'azienda non utilizza mai
• hardcodare il markup del modulo all'interno dei template di pagina invece di incorporare il modello gestito
• revisionare solo l'output visivo ignorando il percorso operativo

Esempio di pattern di implementazione

Component:
  lead-form

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

Pages:
  /pricing/
  /enterprise/
  /contact/

Questo mantiene un flusso di lavoro coerente su diverse superfici di conversione.

Correlati

• Panoramica del prodotto Forms
• Guida ai moduli
• Componenti
• Pagine
• Esporta e importa