Introducción

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

🎯 ¿Qué hace este módulo?

El módulo Forms te permite recuperar formularios - formularios de contacto, encuestas, registros, formularios de retroalimentación - y recopilar envíos de usuarios con validación, cargas de archivos y notificaciones automatizadas.

Piénsalo como tu constructor de formularios - creas formularios en el panel de administración de OneEntry, los muestras en tu aplicación y recopilas respuestas automáticamente.

📖 Explicación Simple

Imagina que necesitas recopilar información de los usuarios:

• 📞 Formulario de Contacto - nombre, correo electrónico, mensaje, teléfono
• 📋 Encuesta - preguntas de opción múltiple, calificaciones
• 👤 Formulario de Registro - detalles del usuario, preferencias
• 💼 Solicitud de Empleo - carga de currículum, carta de presentación
• 📝 Formulario de Retroalimentación - calificaciones, comentarios, sugerencias
• 🎟️ Registro de Evento - información del asistente, selección de entradas

En lugar de construir formularios desde cero:

• ✅ Crea formularios en el panel de administración de OneEntry (arrastrar y soltar campos)
• ✅ Recupera la estructura del formulario dinámicamente
• ✅ Envía datos a OneEntry (almacenamiento automático)
• ✅ Valida campos (requerido, formato de correo, tipos de archivos)
• ✅ Recibe notificaciones cuando se envían formularios
• ✅ Visualiza respuestas en el panel de administración

Ejemplo del mundo real:

Sin Módulo de Formularios (manual):
- Construir HTML/validación del formulario manualmente ❌
- Configurar backend para almacenar envíos ❌
- Crear tablas de base de datos ❌
- Construir panel de administración para ver respuestas ❌
- Escribir código de notificación por correo ❌

Con Módulo de Formularios (automatizado):
- Crear formulario en el panel de administración ✅
- Recuperar estructura del formulario a través de la API ✅
- Enviar datos → Almacenamiento automático ✅
- Ver respuestas en el panel ✅
- Notificaciones automáticas por correo ✅

✨ Conceptos Clave

¿Qué es un Formulario?

Un formulario es una forma estructurada de recopilar información de los usuarios:

• Campos - Elementos de entrada (texto, correo, casillas de verificación, carga de archivos)
• Validación - Reglas (requerido, formato, longitud mínima/máxima)
• Envíos - Respuestas de usuarios almacenadas en la base de datos
• Estructura - Diseño del formulario definido en OneEntry
• Dinámico - Recupera la estructura del formulario desde la API, renderiza en tu aplicación

Ciclo de Vida del Formulario

1. Crear formulario en el administrador de OneEntry
   ↓
2. Definir campos (nombre, correo, mensaje, etc.)
   ↓
3. Establecer reglas de validación
   ↓
4. Recuperar estructura del formulario a través del SDK
   ↓
5. Renderizar formulario en tu aplicación
   ↓
6. El usuario completa el formulario
   ↓
7. Enviar datos a OneEntry
   ↓
8. Se realiza la validación
   ↓
9. Datos almacenados en la base de datos
   ↓
10. Notificaciones enviadas (correo, webhook)

Tipos de Campos de Formulario

Tipos de campos comunes que puedes usar:

Tipo de Campo	Descripción	Ejemplo de Uso
texto	Entrada de texto corto	Nombre, Título, Ciudad
correo	Dirección de correo con validación	Correo de contacto
textarea	Texto de varias líneas	Mensaje, Comentarios, Biografía
número	Entrada numérica	Edad, Cantidad, Teléfono
checkbox	Casilla de verificación única o múltiple	Aceptación de términos, Preferencias
radio	Opción única de varias	Género, Tamaño, Plan
select	Menú desplegable	País, Categoría, Estado
archivo	Carga de archivos	Currículum, Foto, Documento
fecha	Selector de fecha	Fecha de nacimiento, Fecha del evento

📋 Lo Que Necesitas Saber

Estructura del Formulario

Cada formulario tiene estos campos clave:

{
  id: 123,
  marker: "contact_form",   // Identificador único
  localizeInfos: {
    title: "Contáctanos",    // Título del formulario
    description: "Ponte en contacto" // Descripción del formulario
  },
  fields: [   // Campos del formulario
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Nombre" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = activo, 0 = borrador
  isActive: true,              // El formulario está habilitado
  successMessage: "¡Gracias!" // Mensaje después del envío
}

Validación de Campos

Cada campo puede tener reglas de validación:

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Debe ser completado
  "validation": {
    "format": "email",  // Debe ser un correo válido
    "minLength": 5,     // Mínimo 5 caracteres
    "maxLength": 100,   // Máximo 100 caracteres
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Regex personalizado
  }
}

Reglas de validación comunes:

• isRequired - El campo debe ser completado
• minLength - Longitud mínima de texto
• maxLength - Longitud máxima de texto
• format - Formato de correo, teléfono, URL
• pattern - Patrón regex personalizado
• min / max - Rango numérico
• fileTypes - Extensiones de archivo permitidas
• maxFileSize - Tamaño máximo del archivo

---

📊 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	Recuperar formulario específico en el código

Nota: Para crear/editar formularios, usa el panel de administración de OneEntry. El SDK es para recuperar formularios y enviar datos.

---

❓ Preguntas Comunes (FAQ)

¿Cómo creo o edito formularios?

Los formularios se crean en el panel de administración de OneEntry:

1. Inicia sesión en el administrador de OneEntry
2. Ve a la sección de Formularios
3. Crea un nuevo formulario o edita uno existente
4. Agrega campos (arrastrar y soltar)
5. Configura las reglas de validación
6. Activa el formulario

El SDK es para recuperar formularios y enviar datos, no para crear formularios.

---

¿Cómo valido los datos del formulario antes de enviarlos?

Usa la validación del navegador + verificaciones manuales:

---

¿Puedo cargar archivos con formularios?

¡Sí! Usa el módulo FileUploading y agrega file a tu campo:

Aprende más: FormsData Module

---

¿Puedo enviar notificaciones personalizadas cuando se envía un formulario?

Sí, configura en el panel de administración de OneEntry:

• Notificaciones por correo al administrador/usuario
• Notificaciones webhook a tu servidor
• Integración con el módulo de Eventos

---

¿Cómo manejo los errores de envío de formularios?

Siempre usa try/catch

---

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

No directamente en el SDK, pero puedes implementarlo en tu interfaz de usuario

---

💡 Notas Importantes

Los Formularios se Crean en el Panel de Administración

Recuerda: El SDK es para recuperar formularios y enviar datos, no para crear formularios.

Para crear/editar formularios: Usa el panel de administración de OneEntry o la API de administración.

---

Siempre Valida los Datos

✅ La validación del lado del cliente no es suficiente:

• Valida en el cliente (mejor experiencia de usuario)
• Valida en el servidor (OneEntry hace esto automáticamente)

---

Maneja las Cargas de Archivos con Cuidado

✅ Mejores prácticas para cargas de archivos:

• Valida el tipo de archivo antes de la carga
• Verifica los límites de tamaño de archivo
• Muestra el progreso de la carga
• Maneja errores de carga

---

🎓 Mejores Prácticas

✅ Lo que debes hacer:

• Usa marcadores para referenciar formularios (no IDs)
• Valida datos en el cliente y en el servidor
• Muestra estados de carga durante el envío
• Proporciona mensajes de error claros
• Desactiva el botón de envío después de un envío exitoso
• Limpia el formulario después de un envío exitoso
• Maneja errores de carga de archivos de manera adecuada
• Usa try/catch para el manejo de errores

❌ Lo que no debes hacer:

• Codificar IDs de formularios en el código
• Enviar formularios sin validación
• Ignorar el manejo de errores
• Permitir envíos duplicados
• Cargar archivos sin validación de tamaño/tipo
• Mostrar errores técnicos a los usuarios
• Olvidar proporcionar retroalimentación al usuario
• Omitir estados de carga

---

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

Definición del módulo Forms

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

Ejemplos de uso avanzado se pueden encontrar en la Introducción a Formularios.

---

🔗 Documentación Relacionada

• FormsData Module - Ver y gestionar envíos de formularios
• Events Module - Configurar notificaciones automatizadas al enviar formularios
• FileUploading Module - Manejar cargas de archivos en formularios
• Users Module - Gestionar usuarios que envían formularios

---