Introdução

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

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

---

🎯 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 - para que você possa renderizá-los em seu aplicativo. Você cria formulários no painel de administração do OneEntry; o SDK busca sua estrutura (campos, validadores, rótulos localizados) dinamicamente. A coleta das submissões reais é gerenciada pelo módulo FormsData.

🚀 Início Rápido

Inicialize o módulo a partir de defineOneEntry:

const { Forms } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque um único formulário pelo seu marcador e leia seus campos:

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

Para listar todos os formulários (paginados), use getAllForms(langCode, offset, limit), que retorna um objeto { total, items }.

✨ Conceitos Chave

O que é um Formulário?

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

• Campos (attributes) - elementos de entrada, cada um um atributo com um type (string, text, file, list, …)
• Validadores (validators) - regras por campo (obrigatório, comprimento da string, formato de e-mail)
• Estrutura - layout e rótulos localizados definidos no administrador do OneEntry
• Submissões - respostas dos usuários, enviadas e recuperadas via o módulo FormsData

Tipos de Campos de Formulário

O type de cada campo é um AttributeType. Valores comuns:

Tipo (AttributeType)	Descrição	Uso de Exemplo
string	Texto curto em uma linha	Nome, Título, Cidade
text / textWithHeader	Texto em várias linhas	Mensagem, Comentários, Biografia
integer / real / float	Entrada numérica	Idade, Quantidade, Preço
date / dateTime / time	Seletores de data e hora	Data de nascimento, Data do evento
list	Dropdown / seleção múltipla de opções	País, Categoria
radioButton	Escolha única entre opções	Tamanho, Plano
file / image	Upload de arquivo / imagem	Currículo, Foto, Documento
groupOfImages	Múltiplas imagens	Galeria
entity	Referência a outra entidade	Produto ou página vinculada

Nota: O e-mail é um campo string com o emailInspectionValidator habilitado — não há um tipo de campo email separado.

📋 O que Você Precisa Saber

Estrutura do Formulário

Cada formulário (IFormsEntity) possui um id, um identifier (marcador), um type opcional ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (título, mensagem de sucesso, …) e um array de attributes de campos. Cada campo tem um marker, type, localizeInfos, e um objeto validators:

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

Validadores comuns:

• requiredValidator — { strict: boolean }, o campo deve ser preenchido
• stringInspectionValidator — { stringMin, stringMax, stringLength }, restrições de comprimento de texto
• emailInspectionValidator — boolean, impõe formato de e-mail
• defaultValueValidator — valor padrão mais texto de erro personalizado opcional

O conjunto de validadores é extensível — tipos de validadores adicionais podem ser retornados pela API.

Formulários são criados no painel de administração

O SDK é para buscar formulários (e, via o módulo FormsData, submeter dados) — não para criar ou editar formulários. Para construir ou alterar um formulário, use o painel de administração do OneEntry: abra a seção de Formulários, adicione campos, configure regras de validação e ative o formulário.

---

📊 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 pelo marcador	Buscar formulário específico no código

Ambos os métodos são públicos — nenhuma autorização de usuário é necessária.

---

❓ Perguntas Comuns (FAQ)

Como eu crio ou edito formulários?

Os formulários são criados e editados no painel de administração do OneEntry (seção de Formulários), não via o SDK. O SDK apenas busca estruturas de formulários e submete dados.

---

Posso fazer upload de arquivos com formulários?

Sim. Adicione um campo file / image / groupOfImages ao seu formulário; submissões com arquivos são tratadas por FormData.postFormsData(), que os envia através do módulo FileUploading automaticamente. Veja o módulo FormsData.

---

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

Não diretamente no SDK — implemente a lógica de mostrar/ocultar na sua própria interface de usuário com base nos valores dos campos do formulário buscado.

---

🎓 Melhores Práticas

• Referencie formulários pelo seu identifier (marcador), não pelo ID numérico.
• Renderize campos e estado obrigatório a partir dos validators de cada campo para que sua interface corresponda à validação do lado do servidor.
• Use try/catch em torno das buscas e trate a forma de retorno IError.

---

🔗 Documentação Relacionada

• Módulo FormsData - Submeter e gerenciar submissões de formulários
• Módulo Events - Configurar notificações automáticas na submissão de formulários
• Módulo FileUploading - Lidar com uploads de arquivos em formulários
• Módulo Users - Gerenciar usuários que submetem formulários

---