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:
Without Forms Module (manual):
- Build form HTML/validation manually ❌
- Set up backend to store submissions ❌
- Create database tables ❌
- Build admin panel to view responses ❌
- Write email notification code ❌
With Forms Module (automated):
- Create form in admin panel ✅
- Fetch form structure via API ✅
- Submit data → Auto-stored ✅
- View responses in dashboard ✅
- Auto email notifications ✅
✨ 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. Create form in OneEntry admin
↓
2. Define fields (name, email, message, etc.)
↓
3. Set validation rules
↓
4. Fetch form structure via SDK
↓
5. Render form in your app
↓
6. User fills form
↓
7. Submit data to OneEntry
↓
8. Validation happens
↓
9. Data stored in database
↓
10. Notifications sent (email, webhook)
Tipos de Campos de 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 |
| Endereço de e-mail com validação | E-mail de contato | |
| textarea | Texto em várias linhas | Mensagem, Comentários, Bio |
| 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", // Unique identifier
localizeInfos: {
title: "Contact Us", // Form title
description: "Get in touch" // Form description
},
fields: [ // Form fields
{
marker: "name",
type: "text",
localizeInfos: { title: "Name" },
isRequired: true,
validation: { minLength: 2, maxLength: 50 }
},
],
statusId: 1, // 1 = active, 0 = draft
isActive: true, // Is form enabled
successMessage: "Thank you!" // Message after submission
}
Validação de Campos
Cada campo pode ter regras de validação:
{
"marker": "email",
"type": "email",
"isRequired": true, // Must be filled
"validation": {
"format": "email", // Must be valid email
"minLength": 5, // Min 5 characters
"maxLength": 100, // Max 100 characters
"pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$" // Custom regex
}
}
Regras de validação comuns:
isRequired- O campo deve ser preenchidominLength- Comprimento mínimo do textomaxLength- Comprimento máximo do textoformat- Formato de e-mail, telefone, URLpattern- Padrão regex personalizadomin/max- Faixa numéricafileTypes- Extensões de arquivo permitidasmaxFileSize- 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:
- Faça login no OneEntry admin
- Vá para a seção de Formulários
- Crie um novo formulário ou edite um existente
- Adicione campos (arraste e solte)
- Configure as regras de validação
- 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 de 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
💡 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:
- Codificar IDs de formulários no código
- Enviar formulários sem validação
- Ignorar o tratamento de erros
- Permitir envios duplicados
- Fazer upload de arquivos sem validação de tamanho/tipo
- Mostrar erros técnicos para os usuários
- Esquecer de fornecer feedback ao usuário
- Pular 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