Documentação do Desenvolvedor de Formulários

Os formulários são modelos de envio gerenciados centralmente incorporados em Páginas e Componentes do FaceFlow.

Eles permitem que equipes técnicas definam fluxos de solicitação e captação reutilizáveis que podem ser renderizados de forma compatível com cache, processados no momento do envio e gerenciados como ativos de negócio estruturados.

Responsabilidade Principal

Um formulário é responsável por:

• definições de formulário reutilizáveis
• esquema de campos
• renderização em tempo de execução
• validação e tratamento de envio
• roteamento de notificações
• captura de entradas
• reutilização em várias Páginas ou Componentes

Um formulário deve modelar um fluxo de trabalho empresarial de forma clara. Se uma única definição tentar lidar com vários fluxos de trabalho não relacionados, tanto as operações quanto os relatórios ficam prejudicados.

Modelo de Formulário Principal

Um formulário geralmente combina:

• uma identidade de formulário estável
• um esquema de campos
• configuração de apresentação
• comportamento de sucesso e notificações
• regras de tratamento de envio
• armazenamento e gestão de entradas

Na prática, a camada de formulário define tanto o que o visitante pode enviar quanto como o negócio recebe e processa essa submissão.

Conceitualmente:

{
  "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 Campo Suportados

Os tipos de campo suportados incluem:

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

Os conjuntos de campos devem permanecer alinhados com o fluxo operacional. Um formulário que coleta dados que o negócio não utiliza cria atrito tanto para visitantes quanto para as equipes internas.

Exemplo de Definição de Formulário

Uma revisão técnica deve ser capaz de raciocinar sobre o modelo rapidamente:

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

Isso torna possível discutir o contrato de campos, dados obrigatórios e a propriedade do fluxo de trabalho antes que o formulário seja incorporado em qualquer lugar.

Incorporação em Tempo de Execução

Os formulários são tipicamente incorporados em seções de página através de Componentes.

Um marcador de incorporação comum é:

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

Exemplo de seção:

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

Isso permite que a estrutura da página permaneça reutilizável enquanto o modelo de formulário real é gerenciado centralmente.

Incorporações Fixas vs Incorporações Baseadas em Campo

Existem dois padrões comuns de incorporação.

Use um id de formulário gerenciado fixo quando o template deve sempre renderizar um Formulário específico:

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

Use uma incorporação baseada em campo quando um Componente expõe um campo formSelect e os autores devem escolher o Formulário gerenciado no momento da autoria:

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

Regra de decisão:

• incorporação fixa -> um fluxo de trabalho estável de propriedade do template
• incorporação baseada em campo -> Componente reutilizável com fluxo selecionável pelo autor

Fluxo de Envio

Em alto nível:

1. o formulário é definido centralmente
2. ele é incorporado em uma Página através de um Componente
3. o visitante envia entrada estruturada
4. validação e tratamento de envio são executados
5. a submissão é armazenada e roteada para o fluxo de trabalho empresarial relevante

Conceitualmente:

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

Padrão de Integração

O caminho de integração limpo é:

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

Isso mantém o comportamento do formulário centralizado enquanto permite que Páginas e Componentes permaneçam reutilizáveis.

Notificações e Entradas

Os formulários não se tratam apenas da captura no front-end. Eles também suportam o lado operacional das submissões.

Capacidades típicas incluem:

• roteamento de notificações
• gestão de entradas de submissão
• revisão de entradas
• fluxos de exportação

As equipes técnicas devem revisar todo o caminho operacional, não apenas se o formulário é exibido visualmente na página.

Orientações sobre Contrato de Campos

Mantenha o contrato de campos estreito o suficiente para que o fluxo de trabalho permaneça óbvio.

Padrões típicos:

• contato ou solicitação de demonstração -> text, email, textarea, select opcional
• fluxo de qualificação -> text, email, select, number
• captação com upload assistido -> adicione file apenas quando o negócio realmente processar anexos

Prefira um contrato de fluxo de trabalho claro ao invés de um formulário inchado que tenta capturar todos os caminhos possíveis de lead.

Estratégia de Reuso

Um bom design de formulário geralmente favorece o reuso.

Se várias Páginas compartilham o mesmo fluxo de trabalho empresarial, elas geralmente devem compartilhar o mesmo modelo de Formulário.

Isso melhora:

• manutenibilidade
• consistência dos contratos de campo
• comportamento de notificações
• relatórios e tratamento a jusante

Exemplo:

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

Se o fluxo de trabalho for o mesmo, o Formulário geralmente deve ser o mesmo.

Orientações Técnicas

• modele cada Formulário em torno de um fluxo de trabalho empresarial
• reutilize uma definição de formulário entre Páginas onde o fluxo for o mesmo
• mantenha os requisitos de campos alinhados com as necessidades operacionais reais
• evite duplicação específica de página quando um modelo compartilhado funcionar
• revise renderização, envio, notificação e tratamento de entradas em conjunto
• teste o caminho real de submissão antes da liberação

Anti-padrões

Evite:

• criar um novo Formulário para cada Página quando o fluxo for idêntico
• combinar caminhos de lead não relacionados em um único Formulário inchado
• coletar dados opcionais que o negócio nunca utiliza
• codificar estaticamente o markup do formulário dentro de templates de página em vez de incorporar o modelo gerenciado
• revisar apenas a saída visual e ignorar o caminho operacional

Exemplo de Padrão de Construção

Component:
  lead-form

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

Pages:
  /pricing/
  /enterprise/
  /contact/

Isso mantém um fluxo de trabalho consistente em várias superfícies de conversão.

Relacionado

• Visão Geral do Produto de Formulários
• Guia de Formulários
• Componentes
• Páginas
• Exportação e Importação