# Formulário

Os **Formulários da Hablla** permitem criar interfaces de captura de dados por **arrastar e soltar** (drag-and-drop).\
Você monta o layout, configura cada campo e publica para uso em páginas, fluxos e integrações.

> **Como funciona:** escolha os componentes, arraste para a área de edição e ajuste as propriedades nas abas de configuração de cada campo.

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2F3SjZEXBQ5v1asPy1QVXr%2Fimage.png?alt=media&#x26;token=ae11e60f-e0d5-4f79-b4e0-d5e3acc9e242" alt=""><figcaption></figcaption></figure>

### Biblioteca de componentes

#### Basic

* **Text Field**: campo de texto curto (ex.: nome).
* **Text Area**: texto longo (observações).
* **Number**: números inteiros/decimais.
* **Password**: senha (oculta).
* **Checkbox**: verdadeiro/falso.
* **Select Boxes**: múltipla seleção por checkboxes.
* **Select**: lista suspensa (uma opção).
* **Radio**: seleção única por botões de rádio.
* **Button**: botões de ação (Enviar, Voltar etc.).

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2Fk5vhbugqRp8y1FpEskB1%2Fimage.png?alt=media&#x26;token=789ef22c-a75e-4b4e-8615-39373aca39f4" alt=""><figcaption></figcaption></figure>

#### Advanced

* **Email** • **Url** • **Phone Number**
* **Tags**: múltiplos valores com chips.
* **Address**: endereço estruturado.
* **Date/Time** • **Day** • **Time**
* **Currency**: valores monetários.
* **Survey**: matriz de perguntas.
* **Signature**: assinatura digital.

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2F04JVMgFNiIRM2CUA1VTz%2Fimage.png?alt=media&#x26;token=ccd23fed-2383-4686-b5df-031ca0da2775" alt=""><figcaption></figcaption></figure>

#### Layout

* **HTML Element**: bloco HTML livre.
* **Content**: texto estático/MD.
* **Columns**: colunas responsivas.
* **Field Set** • **Panel**: agrupar campos.
* **Table**: grade tabular simples.
* **Tabs**: navegação por abas.
* **Well**: caixa de destaque.

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2FNmucVuQoovoIv14Uzxnu%2Fimage.png?alt=media&#x26;token=cdd184c0-3017-4e7b-a758-93d6bb279209" alt=""><figcaption></figcaption></figure>

#### Data

* **Hidden**: valor oculto (ex.: UTM).
* **Container**: objeto com subcampos.
* **Data Map**: pares chave/valor dinâmicos.
* **Data Grid / Edit Grid**: listas editáveis (linhas repetíveis).

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2FXxxL7Xn59DbimB5L5h7h%2Fimage.png?alt=media&#x26;token=fac1d8d3-2f01-4ccc-a983-1f0142526840" alt=""><figcaption></figcaption></figure>

#### Premium

* **File**: upload de arquivos.
* **Nested Form**: reaproveitar outro formulário.
* **Custom**: componente de lógica própria.

<figure><img src="https://1879311494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrmxWrIrMauHcIrsuqfGq%2Fuploads%2FF2inLU3DDqpBLdUo5Ujr%2Fimage.png?alt=media&#x26;token=54324009-4179-44b9-8da4-3b5e61650c1b" alt=""><figcaption></figcaption></figure>

***

### Configuração de cada campo

Cada componente possui abas de configuração. As mais usadas:

* **Display (Exibição)**\
  Rótulo, placeholder, ajuda (tooltip), posição do rótulo, máscara de entrada e de exibição, CSS de classe, visibilidade.
* **Data (Dados)**\
  Chave interna (`key`), valor padrão, fonte de dados (estático, remoto), mapa de valor/rótulo, persistência.
* **Validation (Validação)**\
  Obrigatoriedade, tamanho mínimo/máximo, regex, limites numéricos, mensagens de erro personalizadas.
* **API**\
  Nome de propriedade, referência para integrações e webhooks.
* **Conditional (Condição)**\
  Mostrar/ocultar baseado em regras (ex.: “mostrar *Telefone* se *Receber contato por WhatsApp* = Sim”).
* **Logic (Lógica)**\
  Ações ao mudar o valor (preencher automático, copiar de outro campo, executar expressão).
* **Layout**\
  Colunas, largura, responsividade e agrupamentos.

> **Dica:** defina `Label` (o que o usuário vê) e `Key` (o identificador técnico) com nomes claros. Ex.: `Label: Nome`, `Key: nome`.

***

### Exemplo: campo **Nome** (JSON)

Abaixo um exemplo minimalista de um **Text Field** para capturar o nome do contato.\
Você pode copiar, adaptar e reutilizar.

```json
{
  "label": "Nome",
  "placeholder": "Digite seu nome completo",
  "description": "Informe como deseja ser chamado.",
  "tooltip": "Use apenas letras e espaços.",
  "type": "textfield",
  "key": "nome",
  "autocomplete": "name",
  "input": true,
  "validate": {
    "required": true,
    "minLength": 2,
    "maxLength": 120,
    "pattern": "^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$",
    "customMessage": "Digite um nome válido (apenas letras)."
  },
  "widget": {
    "type": "input"
  },
  "persistent": true,
  "clearOnHide": true,
  "hidden": false
}
```

### Melhores práticas

1. **Padronize chaves (`key`)**\
   Use `camelCase` ou `snake_case` e evite espaços (ex.: `telefoneWhatsApp`, `aceiteTermos`).
2. **Valide na borda**\
   Aplique validações (regex, min/max, required) para reduzir dados inválidos e retrabalho.
3. **Use máscaras quando fizer sentido**\
   Ex.: telefone, CPF/CNPJ, CEP. Máscara orienta o preenchimento e reduz erros.
4. **Agrupe o que pertence junto**\
   Use **Panels**, **Field Sets** ou **Tabs** para tornar o formulário escaneável.
5. **Condições deixam o fluxo inteligente**\
   Exiba campos apenas quando forem relevantes para reduzir atrito.
6. **Teste em dispositivos reais**\
   Verifique responsividade e acessibilidade (teclado, leitores de tela, contraste).

***

### Publicação e uso

* **Salvar e pré-visualizar:** confira erros de validação e responsividade.
* **Integrar em fluxos:** use o formulário para capturar leads, abrir tickets, alimentar Pessoas/Organizações ou disparar automações.
* **Exportar envios:** combine com relatórios para analisar conversões e qualidade de dados.

***

### Resumo

* Monte formulários por **arrastar e soltar**.
* Configure cada campo pelas abas **Display, Data, Validation, API, Conditional, Logic, Layout**.
* Padronize chaves, valide entradas e use condições para **experiências mais rápidas e assertivas**.

📌 **Dica prática:** comece pequeno (Nome, Email, WhatsApp), valide os campos, publique, e só então evolua o formulário com grupos, lógicas e grids conforme o caso de uso.