Documentación para desarrolladores de Formularios

Los formularios son modelos de envío gestionados de forma centralizada e incrustados en Páginas y Componentes de FaceFlow.

Permiten a los equipos técnicos definir flujos de trabajo de consulta e ingreso reutilizables que pueden renderizarse de forma segura para la caché, procesarse en el momento del envío y gestionarse como activos empresariales estructurados.

Responsabilidad principal

Un Formulario es responsable de:

• definiciones de formulario reutilizables
• esquema de campos
• renderizado en tiempo de ejecución
• validación y manejo de envíos
• enrutamiento de notificaciones
• captura de entradas
• reutilización a través de múltiples Páginas o Componentes

Un Formulario debe modelar con claridad un único flujo de trabajo empresarial. Si una definición intenta manejar varios flujos no relacionados, tanto las operaciones como los informes se debilitan.

Modelo central del formulario

Un Formulario normalmente combina:

• una identidad de formulario estable
• un esquema de campos
• configuración de presentación
• comportamiento de éxito y notificación
• reglas de manejo de envío
• almacenamiento y gestión de entradas

En la práctica, la capa de formulario define tanto lo que el visitante puede enviar como cómo la empresa recibe y procesa ese envío.

Conceptualmente:

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

Tipos de campos compatibles

Los tipos de campo compatibles incluyen:

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

Los conjuntos de campos deben mantenerse alineados con el flujo de trabajo operacional. Un Formulario que recopila datos que la empresa no utiliza crea fricción tanto para los visitantes como para los equipos internos.

Ejemplo de definición de formulario

Una revisión técnica debería poder razonar sobre el modelo rápidamente:

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

Esto hace posible discutir el contrato de campos, los datos requeridos y la propiedad del flujo de trabajo antes de que el Formulario se incruste en cualquier lugar.

Incrustación en tiempo de ejecución

Los formularios normalmente se incrustan en secciones de la página a través de Componentes.

Un marcador de incrustación común es:

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

Sección de ejemplo:

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

Esto permite que la estructura de la página siga siendo reutilizable mientras el modelo real del formulario se mantiene gestionado de forma centralizada.

Incrustaciones fijas vs. incrustaciones basadas en campos

Hay dos patrones comunes de incrustación.

Use un id de formulario gestionado fijo cuando la plantilla deba renderizar siempre un Formulario específico:

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

Use una incrustación basada en campo cuando un Componente exponga un campo formSelect y los autores deban elegir el Formulario gestionado en el momento de la autoría:

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

Regla de decisión:

• incrustación fija -> un flujo de trabajo estable propiedad de la plantilla
• incrustación basada en campo -> Componente reutilizable con flujo seleccionable por el autor

Flujo de envío

A alto nivel:

1. el Formulario se define de forma centralizada
2. se incrusta en una Página mediante un Componente
3. el visitante envía datos estructurados
4. se ejecutan la validación y el manejo del envío
5. el envío se almacena y se enruta al flujo de trabajo empresarial correspondiente

Conceptualmente:

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

Patrón de integración

La vía de integración limpia es:

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

Eso mantiene el comportamiento del formulario centralizado al mismo tiempo que permite que las Páginas y Componentes sigan siendo reutilizables.

Notificaciones y entradas

Los formularios no solo tratan de la captura en el front-end. También admiten el lado operacional de los envíos.

Las capacidades típicas incluyen:

• enrutamiento de notificaciones
• gestión de entradas de envíos
• revisión de entradas
• flujos de trabajo de exportación

Los equipos técnicos deben revisar la ruta operacional completa, no solo si el formulario se renderiza visualmente en la página.

Guía del contrato de campos

Mantenga el contrato de campos lo suficientemente estrecho como para que el flujo de trabajo sea obvio.

Patrones típicos:

• solicitud de contacto o demo -> text, email, textarea, select opcional
• flujo de calificación -> text, email, select, number
• ingreso asistido por carga -> añadir file solo cuando la empresa realmente procese adjuntos

Prefiera un contrato de flujo de trabajo claro en lugar de un formulario sobredimensionado que intente capturar todos los posibles caminos de leads.

Estrategia de reutilización

Un buen diseño de Formularios suele favorecer la reutilización.

Si varias Páginas comparten el mismo flujo de trabajo empresarial, normalmente deberían compartir el mismo modelo de Formulario.

Esto mejora:

• mantenibilidad
• consistencia del contrato de campos
• comportamiento de notificaciones
• informes y manejo downstream

Ejemplo:

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

Si el flujo de trabajo es el mismo, normalmente el Formulario debería ser el mismo.

Orientación técnica

• modele cada Formulario alrededor de un flujo de trabajo empresarial
• reutilice una definición de formulario en varias Páginas donde el flujo sea el mismo
• mantenga los requisitos de los campos alineados con las necesidades operativas reales
• evite la duplicación específica de la página cuando un modelo compartido funcione
• revise renderizado, envío, notificación y manejo de entradas de forma conjunta
• pruebe la ruta de envío real antes del lanzamiento

Anti-patrones

Evite:

• crear un nuevo Formulario para cada Página cuando el flujo sea idéntico
• combinar caminos de leads no relacionados en un solo Formulario sobredimensionado
• recopilar datos opcionales que la empresa nunca utiliza
• codificar el marcado del formulario dentro de las plantillas de página en lugar de incrustar el modelo gestionado
• revisar solo la salida visual e ignorar la ruta operacional

Patrón de construcción de ejemplo

Component:
  lead-form

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

Pages:
  /pricing/
  /enterprise/
  /contact/

Eso mantiene un flujo de trabajo consistente en varias superficies de conversión.

Relacionado

• Resumen del producto de Formularios
• Guía de Formularios
• Componentes
• Páginas
• Exportar e Importar