# Formulario

Los **Formularios de Hablla** permiten crear interfaces de captura de datos mediante **arrastrar y soltar** (drag-and-drop).\
Usted monta el diseño, configura cada campo y publica para su uso en páginas, flujos e integraciones.

> **Cómo funciona:** elija los componentes, arrástrelos al área de edición y ajuste las propiedades en las pestañas de configuración de cada campo.

<figure><img src="https://4006966930-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

#### Básico

* **Campo de texto**: campo de texto corto (ej.: nombre).
* **Área de texto**: texto largo (observaciones).
* **Número**: números enteros/decimales.
* **Contraseña**: contraseña (oculta).
* **Casilla de verificación**: verdadero/falso.
* **Cuadros de selección**: selección múltiple mediante checkboxes.
* **Seleccionar**: lista desplegable (una opción).
* **Radio**: selección única mediante botones de radio.
* **Botón**: botones de acción (Enviar, Volver, etc.).

<figure><img src="https://4006966930-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>

#### Avanzado

* **Correo electrónico** • **Url** • **Número de teléfono**
* **Etiquetas**: múltiples valores con chips.
* **Dirección**: dirección estructurada.
* **Fecha/Hora** • **Día** • **Equipo**
* **Moneda**: valores monetarios.
* **Encuesta**: matriz de preguntas.
* **Firma**: firma digital.

<figure><img src="https://4006966930-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>

#### Diseño

* **Elemento HTML**: bloque HTML libre.
* **Contenido**: texto estático/MD.
* **Columns**: columnas responsivas.
* **Conjunto de campos** • **Panel**: agrupar campos.
* **Tabla**: cuadrícula tabular simple.
* **Pestañas**: navegación por pestañas.
* **Well**: cuadro destacado.

<figure><img src="https://4006966930-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>

#### Datos

* **Oculto**: valor oculto (ej.: UTM).
* **Contenedor**: objeto con subcampos.
* **Mapa de datos**: pares clave/valor dinámicos.
* **Cuadrícula de datos / Cuadrícula editable**: listas editables (filas repetibles).

<figure><img src="https://4006966930-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

* **Archivo**: carga de archivos.
* **Formulario anidado**: reutilizar otro formulario.
* **Personalizado**: componente con lógica propia.

<figure><img src="https://4006966930-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>

***

### Configuración de cada campo

Cada componente posee pestañas de configuración. Las más usadas:

* **Display (Visualización)**\
  Etiqueta, placeholder, ayuda (tooltip), posición de la etiqueta, máscara de entrada y de visualización, clase CSS, visibilidad.
* **Data (Datos)**\
  Clave interna (`key`), valor por defecto, fuente de datos (estático, remoto), mapa de valor/etiqueta, persistencia.
* **Validation (Validación)**\
  Obligatoriedad, tamaño mínimo/máximo, regex, límites numéricos, mensajes de error personalizados.
* **API**\
  Nombre de propiedad, referencia para integraciones y webhooks.
* **Conditional (Condición)**\
  Mostrar/ocultar basado en reglas (ej.: “mostrar *Teléfono* si *Recibir contacto por WhatsApp* = Sí”).
* **Logic (Lógica)**\
  Acciones al cambiar el valor (relleno automático, copiar de otro campo, ejecutar expresión).
* **Diseño**\
  Columnas, ancho, capacidad de respuesta y agrupamientos.

> **Consejo:** defina `Etiqueta` (lo que el usuario ve) y `Clave` (el identificador técnico) con nombres claros. Ej.: `Etiqueta: Nombre`, `Clave: nombre`.

***

### Ejemplo: campo **Nombre** (JSON)

A continuación un ejemplo minimalista de un **Campo de texto** para capturar el nombre del contacto.\
Puede copiar, adaptar y reutilizar.

```json
{
  "label": "Nombre",
  "placeholder": "Ingrese su nombre completo",
  "description": "Indique cómo desea ser llamado.",
  "tooltip": "Use solo letras y espacios.",
  "type": "textfield",
  "key": "nombre",
  "autocomplete": "name",
  "input": true,
  "validate": {
    "required": true,
    "minLength": 2,
    "maxLength": 120,
    "pattern": "^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$",
    "customMessage": "Ingrese un nombre válido (solo letras)."
  },
  "widget": {
    "type": "input"
  },
  "persistent": true,
  "clearOnHide": true,
  "hidden": false
}
```

### Mejores prácticas

1. **Estandarice claves (`key`)**\
   Use `camelCase` o `snake_case` y evite espacios (ej.: `telefonoWhatsApp`, `aceptaTerminos`).
2. **Valide en el borde**\
   Aplique validaciones (regex, min/max, required) para reducir datos inválidos y retrabajo.
3. **Use máscaras cuando tenga sentido**\
   Ej.: teléfono, CPF/CNPJ, CEP. La máscara guía el llenado y reduce errores.
4. **Agrupe lo que pertenece junto**\
   Use **Paneles**, **Conjuntos de campos** o **Pestañas** para hacer el formulario escaneable.
5. **Las condiciones hacen el flujo inteligente**\
   Muestre campos solo cuando sean relevantes para reducir fricción.
6. **Pruebe en dispositivos reales**\
   Verifique la capacidad de respuesta y accesibilidad (teclado, lectores de pantalla, contraste).

***

### Publicación y uso

* **Guardar y previsualizar:** revise errores de validación y capacidad de respuesta.
* **Integrar en flujos:** use el formulario para capturar leads, abrir tickets, alimentar Personas/Organizaciones o disparar automatizaciones.
* **Exportar envíos:** combínelo con informes para analizar conversiones y calidad de datos.

***

### Resumen

* Monte formularios por **arrastrar y soltar**.
* Configure cada campo mediante las pestañas **Display, Data, Validation, API, Conditional, Logic, Layout**.
* Estandarice claves, valide entradas y use condiciones para **experiencias más rápidas y acertadas**.

📌 **Consejo práctico:** comience pequeño (Nombre, Correo, WhatsApp), valide los campos, publique, y solo entonces evolucione el formulario con grupos, lógicas y grids según el caso de uso.