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:

Without Forms Module (manual):
- Build form HTML/validation manually ❌
- Set up backend to store submissions ❌
- Create database tables ❌
- Build admin panel to view responses ❌
- Write email notification code ❌

With Forms Module (automated):
- Create form in admin panel ✅
- Fetch form structure via API ✅
- Submit data → Auto-stored ✅
- View responses in dashboard ✅
- Auto email notifications ✅

✨ 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 los 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. Create form in OneEntry admin
   ↓
2. Define fields (name, email, message, etc.)
   ↓
3. Set validation rules
   ↓
4. Fetch form structure via SDK
   ↓
5. Render form in your app
   ↓
6. User fills form
   ↓
7. Submit data to OneEntry
   ↓
8. Validation happens
   ↓
9. Data stored in database
   ↓
10. Notifications sent (email, 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
file	Carga de archivos	Currículum, Foto, Documento
date	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",   // Unique identifier
  localizeInfos: {
    title: "Contact Us",    // Form title
    description: "Get in touch" // Form description
  },
  fields: [   // Form fields
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Name" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = active, 0 = draft
  isActive: true,              // Is form enabled
  successMessage: "Thank you!" // Message after submission
}

Validación de Campos

Cada campo puede tener reglas de validación:

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Must be filled
  "validation": {
    "format": "email",  // Must be valid email
    "minLength": 5,     // Min 5 characters
    "maxLength": 100,   // Max 100 characters
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Custom regex
  }
}

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 de 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 electrónico al administrador/usuario
• Notificaciones por 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 los errores de carga

---

🎓 Mejores Prácticas

✅ Lo que debes hacer:

• Usa marcadores para referenciar formularios (no IDs)
• Valida los 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 los errores de carga de archivos con gracia
• 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(
  "tu-url-del-proyecto", {
    "token": "tu-token-de-aplicación"
  }
);

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

---