Introducción

Obtén formularios dinámicos con envíos en tiempo real y recolección de datos.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/forms

---

🎯 ¿Qué hace este módulo?

El módulo Forms te permite recuperar formularios - formularios de contacto, encuestas, registros, formularios de retroalimentación - para que puedas renderizarlos en tu aplicación. Construyes formularios en el panel de administración de OneEntry; el SDK obtiene su estructura (campos, validadores, etiquetas localizadas) de manera dinámica. La recolección de los envíos reales es manejada por el módulo FormsData.

🚀 Inicio Rápido

Inicializa el módulo desde defineOneEntry:

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

Obtén un solo formulario por su marcador y lee sus 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 los formularios (paginados) usa getAllForms(langCode, offset, limit), que devuelve un objeto { total, items }.

✨ Conceptos Clave

¿Qué es un Formulario?

Un formulario (IFormsEntity) es una forma estructurada de recolectar información de los usuarios:

• Campos (attributes) - elementos de entrada, cada uno un atributo con un type (string, text, file, list, …)
• Validadores (validators) - reglas por campo (requerido, longitud de cadena, formato de correo electrónico)
• Estructura - diseño y etiquetas localizadas definidas en el administrador de OneEntry
• Envíos - respuestas de los usuarios, enviadas y recuperadas a través del módulo FormsData

Tipos de Campos de Formulario

El type de cada campo es un AttributeType. Valores comunes:

Tipo (AttributeType)	Descripción	Ejemplo de Uso
string	Texto corto en una sola línea	Nombre, Título, Ciudad
text / textWithHeader	Texto de varias líneas	Mensaje, Comentarios, Biografía
integer / real / float	Entrada numérica	Edad, Cantidad, Precio
date / dateTime / time	Seleccionadores de fecha y hora	Fecha de nacimiento, Fecha del evento
list	Desplegable / selección múltiple de opciones	País, Categoría
radioButton	Opción única de entre opciones	Tamaño, Plan
file / image	Carga de archivo / imagen	Currículum, Foto, Documento
groupOfImages	Múltiples imágenes	Galería
entity	Referencia a otra entidad	Producto o página vinculada

Nota: El correo electrónico es un campo string con el emailInspectionValidator habilitado; no hay un tipo de campo email separado.

📋 Lo Que Necesitas Saber

Estructura del Formulario

Cada formulario (IFormsEntity) lleva un id, un identifier (marcador), un type opcional ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (título, mensaje de éxito, …) y un array de attributes de campos. Cada campo tiene un marker, type, localizeInfos, y un objeto validators:

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

Validadores comunes:

• requiredValidator — { strict: boolean }, el campo debe ser completado
• stringInspectionValidator — { stringMin, stringMax, stringLength }, restricciones de longitud de texto
• emailInspectionValidator — boolean, hacer cumplir el formato de correo electrónico
• defaultValueValidator — valor por defecto más texto de error personalizado opcional

El conjunto de validadores es extensible; tipos de validadores adicionales pueden ser devueltos por la API.

Los formularios se crean en el panel de administración

El SDK es para obtener formularios (y, a través del módulo FormsData, enviar datos) — no para crear o editar formularios. Para construir o cambiar un formulario, utiliza el panel de administración de OneEntry: abre la sección de Formularios, agrega campos, configura reglas de validación y activa el formulario.

---

📊 Tabla de Referencia Rápida - Métodos

Método	Qué Hace	Cuándo Usar
getAllForms()	Obtener todos los formularios (paginados)	Listar todos los formularios disponibles
getFormByMarker()	Obtener formulario por marcador	Obtener formulario específico en el código

Ambos métodos son públicos; no se requiere autorización de usuario.

---

❓ Preguntas Comunes (FAQ)

¿Cómo creo o edito formularios?

Los formularios se crean y editan en el panel de administración de OneEntry (sección de Formularios), no a través del SDK. El SDK solo obtiene estructuras de formularios y envía datos.

---

¿Puedo subir archivos con formularios?

Sí. Agrega un campo file / image / groupOfImages a tu formulario; los envíos con archivos son manejados por FormData.postFormsData(), que los sube automáticamente a través del módulo FileUploading. Consulta el módulo FormsData.

---

¿Pueden los formularios tener campos condicionales (mostrar/ocultar según otros campos)?

No directamente en el SDK; implementa la lógica de mostrar/ocultar en tu propia interfaz de usuario basada en los valores de los campos del formulario obtenido.

---

🎓 Mejores Prácticas

• Referencia los formularios por su identifier (marcador), no por ID numérico.
• Renderiza los campos y el estado requerido desde los validators de cada campo para que tu interfaz de usuario coincida con la validación del lado del servidor.
• Usa try/catch alrededor de las obtenciones y maneja la forma de retorno IError.

---

🔗 Documentación Relacionada

• Módulo FormsData - Envía y gestiona envíos de formularios
• Módulo Events - Configura notificaciones automáticas al enviar formularios
• Módulo FileUploading - Maneja cargas de archivos en formularios
• Módulo Users - Gestiona usuarios que envían formularios

---