Introdução

Busque formulários dinâmicos com envios em tempo real e coleta de dados.

🎯 O que este módulo faz?

O módulo Forms permite que você recupere formulários - formulários de contato, pesquisas, registros, formulários de feedback - e colete envios de usuários com validação, uploads de arquivos e notificações automatizadas.

Pense nisso como seu construtor de formulários - você cria formulários no painel de administração do OneEntry, os exibe em seu aplicativo e coleta respostas automaticamente.

📖 Explicação Simples

Imagine que você precisa coletar informações dos usuários:

• 📞 Formulário de Contato - nome, e-mail, mensagem, telefone
• 📋 Pesquisa - perguntas de múltipla escolha, avaliações
• 👤 Formulário de Registro - detalhes do usuário, preferências
• 💼 Candidatura a Emprego - upload de currículo, carta de apresentação
• 📝 Formulário de Feedback - avaliações, comentários, sugestões
• 🎟️ Registro para Evento - informações do participante, seleção de ingressos

Em vez de construir formulários do zero:

• ✅ Crie formulários no painel de administração do OneEntry (arraste e solte campos)
• ✅ Busque a estrutura do formulário dinamicamente
• ✅ Envie dados para o OneEntry (armazenamento automático)
• ✅ Valide campos (obrigatório, formato de e-mail, tipos de arquivo)
• ✅ Receba notificações quando os formulários forem enviados
• ✅ Veja as respostas no painel de administração

Exemplo do mundo real:

Sem o Módulo de Formulários (manual):
- Construa HTML/validação do formulário manualmente ❌
- Configure o backend para armazenar envios ❌
- Crie tabelas de banco de dados ❌
- Construa painel de administração para ver respostas ❌
- Escreva código de notificação por e-mail ❌

Com o Módulo de Formulários (automatizado):
- Crie formulário no painel de administração ✅
- Busque a estrutura do formulário via API ✅
- Envie dados → Armazenamento automático ✅
- Veja respostas no painel ✅
- Notificações automáticas por e-mail ✅

✨ Conceitos Chave

O que é um Formulário?

Um formulário é uma maneira estruturada de coletar informações dos usuários:

• Campos - Elementos de entrada (texto, e-mail, caixas de seleção, upload de arquivo)
• Validação - Regras (obrigatório, formato, comprimento mínimo/máximo)
• Envios - Respostas dos usuários armazenadas no banco de dados
• Estrutura - Layout do formulário definido no OneEntry
• Dinâmico - Busque a estrutura do formulário da API, renderize em seu aplicativo

Ciclo de Vida do Formulário

1. Crie o formulário no painel de administração do OneEntry
   ↓
2. Defina os campos (nome, e-mail, mensagem, etc.)
   ↓
3. Defina as regras de validação
   ↓
4. Busque a estrutura do formulário via SDK
   ↓
5. Renderize o formulário em seu aplicativo
   ↓
6. O usuário preenche o formulário
   ↓
7. Envie os dados para o OneEntry
   ↓
8. A validação acontece
   ↓
9. Dados armazenados no banco de dados
   ↓
10. Notificações enviadas (e-mail, webhook)

Tipos de Campos do Formulário

Tipos de campos comuns que você pode usar:

Tipo de Campo	Descrição	Uso Exemplo
texto	Entrada de texto curto	Nome, Título, Cidade
e-mail	Endereço de e-mail com validação	E-mail de contato
textarea	Texto de várias linhas	Mensagem, Comentários, Biografia
número	Entrada numérica	Idade, Quantidade, Telefone
checkbox	Caixa de seleção única ou múltipla	Aceitação de termos, Preferências
radio	Escolha única entre opções	Gênero, Tamanho, Plano
select	Menu suspenso	País, Categoria, Status
file	Upload de arquivo	Currículo, Foto, Documento
date	Seletor de data	Data de nascimento, Data do evento

📋 O que você precisa saber

Estrutura do Formulário

Todo formulário tem esses campos principais:

{
  id: 123,
  marker: "contact_form",   // Identificador único
  localizeInfos: {
    title: "Fale Conosco",  // Título do formulário
    description: "Entre em contato" // Descrição do formulário
  },
  fields: [   // Campos do formulário
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Nome" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = ativo, 0 = rascunho
  isActive: true,              // O formulário está habilitado
  successMessage: "Obrigado!"  // Mensagem após o envio
}

Validação de Campos

Cada campo pode ter regras de validação:

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Deve ser preenchido
  "validation": {
    "format": "email",  // Deve ser um e-mail válido
    "minLength": 5,     // Mínimo 5 caracteres
    "maxLength": 100,   // Máximo 100 caracteres
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Regex personalizado
  }
}

Regras de validação comuns:

• isRequired - O campo deve ser preenchido
• minLength - Comprimento mínimo do texto
• maxLength - Comprimento máximo do texto
• format - Formato de e-mail, telefone, URL
• pattern - Padrão regex personalizado
• min / max - Faixa numérica
• fileTypes - Extensões de arquivo permitidas
• maxFileSize - Tamanho máximo do arquivo

---

📊 Tabela de Referência Rápida - Métodos

Método	O que faz	Quando usar
getAllForms()	Obter todos os formulários (paginados)	Listar todos os formulários disponíveis
getFormByMarker()	Obter formulário por marcador	Buscar formulário específico no código

Nota: Para criar/editar formulários, use o painel de administração do OneEntry. O SDK é para buscar formulários e enviar dados.

---

❓ Perguntas Comuns (FAQ)

Como eu crio ou edito formulários?

Os formulários são criados no painel de administração do OneEntry:

1. Faça login no painel de administração do OneEntry
2. Vá para a seção de Formulários
3. Crie um novo formulário ou edite um existente
4. Adicione campos (arraste e solte)
5. Configure as regras de validação
6. Ative o formulário

O SDK é para buscar formulários e enviar dados, não para criar formulários.

---

Como eu valido os dados do formulário antes de enviar?

Use validação do navegador + verificações manuais:

---

Posso fazer upload de arquivos com formulários?

Sim! Use o módulo FileUploading e adicione file ao seu campo:

Saiba mais: FormsData Module

---

Posso enviar notificações personalizadas quando o formulário for enviado?

Sim, configure no painel de administração do OneEntry:

• Notificações por e-mail para admin/usuário
• Notificações webhook para seu servidor
• Integração com o módulo Events

---

Como eu lido com erros de envio de formulário?

Sempre use try/catch

---

Os formulários podem ter campos condicionais (mostrar/ocultar com base em outros campos)?

Não diretamente no SDK, mas você pode implementar em sua interface de usuário

---

💡 Notas Importantes

Os formulários são criados no Painel de Administração

Lembre-se: O SDK é para buscar formulários e enviar dados, não para criar formulários.

Para criar/editar formulários: Use o painel de administração do OneEntry ou a API Admin.

---

Sempre Valide os Dados

✅ A validação do lado do cliente não é suficiente:

• Valide no cliente (melhor UX)
• Valide no servidor (o OneEntry faz isso automaticamente)

---

Lide com Uploads de Arquivos com Cuidado

✅ Melhores práticas para uploads de arquivos:

• Valide o tipo de arquivo antes do upload
• Verifique os limites de tamanho do arquivo
• Mostre o progresso do upload
• Lide com erros de upload

---

🎓 Melhores Práticas

✅ O que fazer:

• Use marcadores para referenciar formulários (não IDs)
• Valide dados no cliente e no servidor
• Mostre estados de carregamento durante o envio
• Forneça mensagens de erro claras
• Desative o botão de envio após um envio bem-sucedido
• Limpe o formulário após um envio bem-sucedido
• Lide com erros de upload de arquivos de forma elegante
• Use try/catch para tratamento de erros

❌ O que não fazer:

• Codifique IDs de formulários no código
• Envie formulários sem validação
• Ignore o tratamento de erros
• Permita envios duplicados
• Faça upload de arquivos sem validação de tamanho/tipo
• Mostre erros técnicos para os usuários
• Esqueça de fornecer feedback ao usuário
• Pule estados de carregamento

---

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/forms/introduction

Definição do módulo Forms

const { Forms } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

Exemplos de uso avançado podem ser encontrados na Introdução aos Formulários.

---

🔗 Documentação Relacionada

• FormsData Module - Visualizar e gerenciar envios de formulários
• Events Module - Configurar notificações automatizadas no envio de formulários
• FileUploading Module - Lidar com uploads de arquivos em formulários
• Users Module - Gerenciar usuários que enviam formulários

---