Crea Formularios Personalizados con WebBlocks Forms
Diseña el formulario alrededor de las preguntas que tus visitantes necesitan responder. WebBlocks Forms permite elegir campos, validación, pasos y preguntas condicionales, y recopilar los resultados en tu CMS. Un bloque Form nativo coloca el formulario en la página; la bandeja del complemento guarda los envíos.
El ejemplo es Northstar Studio y su formulario Project enquiry. El primer paso pregunta quién escribe y qué proyecto tiene en mente. Elegir Website project revela una pregunta obligatoria sobre el sitio. El segundo recoge descripción, presupuesto y archivo opcionales, y una aceptación. Enviarás como visitante, leerás las respuestas, descargarás el adjunto privado, marcarás la consulta respondida y exportarás CSV.
Se comprobó con el archivo publicado Forms 0.10.5 y WebBlocks CMS 1.105.26, interfaz inglesa, tema claro y datos ficticios. Incluye la integración explícita del proveedor en el host que necesita la instalación ZIP probada. Notificación y copia al visitante muestran deliberadamente Not configured: no se probaron entrega real de correo, webhook externo ni suscripción Campaigns. Sí se probaron localmente el recorrido, filtrado condicional, pasos, descarga privada, estados, CSV e importación Contact Form. Las capturas y nombres de campos y botones permanecen en inglés para facilitar la comparación.
Elegir Forms o Contact Form integrado
| Elección | Cuándo encaja | Dónde llegan los resultados |
|---|---|---|
| Contact Form nativo | Campos estándar de nombre, correo, asunto y mensaje. | Contact Messages. |
| WebBlocks Forms | Campos propios, opciones, pasos, condiciones o adjuntos. | Forms → Submissions. |
Forms no sustituye Contact Form. Puedes usar ambos con bandejas separadas. Importar crea un formulario nuevo del complemento; no traslada mensajes antiguos ni cambia el bloque existente por ti.
El formulario pertenece a un sitio. Sus campos, tratamiento y acciones son del formulario; el bloque guarda su handle. Varias páginas reutilizan la misma definición. Editar un campo cambia todas sus ubicaciones, sin crear una copia por página.
Consulta los contratos y detalles en la referencia de Forms, o la alternativa sencilla en Añadir un formulario de contacto y leer mensajes.
Antes de empezar
Prepara sitio de prueba, página borrador y cuenta Super admin. Forms 0.10.5 declara CMS ^1.92.1 y PHP >=8.3; el catálogo indica PHP ^8.3 y Laravel ^13.0. Comprueba compatibilidad con tu host y los requisitos del CMS. Se necesitan las extensiones PHP JSON y ZIP.
Hay cinco permisos distintos: consultar formularios, gestionarlos, gestionar envíos, exportarlos y cambiar Form Settings. Crear un formulario no concede automáticamente acceso a bandeja o exportaciones. Asigna permisos y sitios adecuados; revisa Roles y permisos.
Necesitarás al administrador del alojamiento para el proveedor, almacenamiento privado, correo y programación de retención. El correo local sirve para aprender, pero comprueba entrega real antes de prometer una respuesta por email. Usa buzones controlados en esa prueba, no las direcciones ficticias siguientes.
El complemento es gratuito en el catálogo WebBlocks. Commerce, Appointments, Memberships y Campaigns no son necesarios para esta consulta. Una respuesta de presupuesto no se convierte en pago ni cita.
1. Instala Forms y completa la integración del host
- Entra como Super admin y abre System → Plugins.
- Selecciona Browse Plugin Catalog, después WebBlocks Forms.
- Revisa versión, compatibilidad y notas.
- Elige Install from Catalog para la versión compatible y Enable Plugin en los detalles.
- Con un ZIP fiable del administrador, usa Plugin ZIP → Upload Plugin ZIP, revísalo y actívalo.
Los nuevos paquetes empiezan desactivados. El CMS actual prepara los cambios de base de datos durante instalación y activación. Si aparece Plugin migrations pending, resuelve la preparación desde los detalles y verifica las tablas. No hay que compilar fuentes para la ruta de catálogo o ZIP del panel.
Aparecen Forms, Submissions, Import Contact Form y Settings bajo Forms. Selecciona Northstar Studio o tu sitio previsto en los selectores disponibles. Un estado saludable de tablas no demuestra que funcionen envío público, correo o retención programada.
Paso de alojamiento para el ZIP probado
En Forms 0.10.5 / CMS 1.105.26, editor y bloque estaban disponibles pero el proveedor no arrancaba automáticamente. El envío público fallaba porque su limitador de frecuencia con nombre no estaba registrado. El host funcional de la guía registra explícitamente el proveedor activo; es parte de la instalación, no un cambio exclusivo de las capturas.
Pide al administrador añadir lo siguiente dentro del método boot() existente de App\Providers\AppServiceProvider en la aplicación host. Conserva la lógica existente. La comprobación del registro solo lo activa cuando Forms está activo:
$this->app->booted(function (): void {
$registry = $this->app->make(
\WebBlocks\Cms\Support\Plugins\PluginRegistry::class
);
if ($registry->isActive('webblocks-forms')) {
$provider = $registry->get('webblocks-forms')?->providerClass();
if ($provider !== null && class_exists($provider)) {
$this->app->register($provider);
}
}
});El administrador debe limpiar configuración obsoleta con php artisan optimize:clear y reiniciar procesos persistentes cuando corresponda. Después prueba un envío real. Esto también carga configuración de Forms, incluidos archivos y tiempos. Si un host más reciente ya arranca el proveedor, verifícalo antes de añadir otra integración innecesaria. No elimines el limitador para ocultar el fallo.
2. Revisa Form Settings del sitio
Abre Forms → Settings en el sitio previsto. Ejemplo:
| Ajuste | Ejemplo | Significado |
|---|---|---|
| Default notification recipient | hello@example.test | Buzón ficticio sin destinatario explícito en el formulario. |
| Store submissions in the CMS | Activado | Revísalo y activa también el almacenamiento en el formulario. |
| Delete submissions after (days) | Vacío | Sin periodo de sitio en este ejemplo. |
| Maximum upload size (KB) | 2048 | Límite del sitio, sujeto al máximo de instalación. |
Selecciona Save. Un destinatario vacío es válido: se resuelve desde Send notifications to del formulario, este valor predeterminado, Contact del sitio, CONTACT_RECIPIENT_EMAIL y finalmente el remitente configurado. Define el destino real deliberadamente en lugar de heredar un último destino no deseado.
La versión probada lee almacenamiento y retención de cada formulario. Cambiar los valores de sitio con nombres similares no actualiza automáticamente los existentes ni establece su borrado. Configura y comprueba su propia sección Handling. La cadena de destinatarios y el límite de archivos del sitio sí se aplican al ejemplo.
3. Crea el formulario y su tratamiento
Abre Forms → Forms → Add form. Introduce Project enquiry en Name, northstar-project-enquiry en Handle y deja Accepting submissions marcado.
El handle usa palabras minúsculas separadas por un guion. Los bloques lo guardan: elígelo antes de colocarlos. Nombre y handle no son lo mismo; cambiar este último desconecta las ubicaciones hasta actualizarlas. En multisitio usa handles distintos en toda la instalación y prueba el destino de cada sitio; este controlador público resuelve por handle.
En Handling, activa Store submissions in the CMS, desactiva Store the submitter's IP address y deja Delete submissions after (days) vacío. Pon Submits per minute, per visitor en 5. Deja Redirect after submit vacío para ver el resultado en la página.
Selecciona Save. El almacenamiento es esencial: desactivarlo evita tanto el registro como las acciones posteriores en esta versión. No es una forma admitida de hacer un formulario solo de correo. Capturar IP es independiente de las señales temporales de protección local.
Un límite menor reduce el máximo de instalación; uno mayor no lo aumenta. Se cuenta por visitante y formulario. La redirección debe ser una ruta del mismo sitio con una sola barra inicial, como /thank-you; prepara y prueba el destino antes. Déjalo vacío durante esta verificación.
4. Configura notificación y copia al visitante
Busca Notification. Mantén Email me when a submission arrives marcado y Send notifications to vacío para heredar el sitio. Especifica destinatario solo si otro buzón gestiona este formulario.
En Reply to sender, activa Send the visitor a copy of what they submitted. Usa una dirección real atendida en Visitors reply to; la imagen usa studio@example.test. Vacío significa que no se añade reply-to. Selecciona Save.
La copia necesita un campo de tipo Email address con dirección válida enviada. Un campo de texto llamado “Email” no equivale. Usa un único campo claro. Ambos resultados se registran por separado; ninguno prueba la llegada al buzón sin comprobarla.
Mantén Webhooks y Mailing list desactivados mientras aprendes. Son acciones opcionales, no requisitos para guardar. Volveremos después de probar la bandeja.
5. Añade los ocho campos
Tras guardar, Fields ofrece Add field. Crea los siguientes. Un mismo Step comparte pantalla; Up y Down ordenan dentro del paso.
| Etiqueta | Tipo | Key | Step | Obligatorio |
|---|---|---|---|---|
| Your name | Single-line text | full_name | 1 | Sí |
| Email address | Email address | 1 | Sí | |
| Project type | Dropdown | project_type | 1 | Sí |
| Current website | Single-line text | current_website | 1 | Sí, solo si coincide la condición |
| Tell us about your project | Paragraph | brief | 2 | Sí |
| Indicative budget (EUR) | Number | budget | 2 | No |
| Attach a short brief | File upload | brief_file | 2 | No |
| I agree that Northstar Studio may use these details to respond to my project enquiry. | Consent | enquiry_consent | 2 | Sí |
Para Your name, elige Single-line text, Key full_name, Required y Step 1. En Validation usa Minimum 2, Maximum 100. En Copy → EN English, Label Your name y Help text How should we address you?. Guarda.
Las claves empiezan por letra y usan minúsculas, dígitos y guiones bajos. Las etiquetas son texto visible; las claves identifican respuestas en almacenamiento, condiciones e integraciones. Cuando hay envíos, las claves existentes quedan bloqueadas. Elígelas estables desde el principio.
El editor muestra ajustes de varios tipos juntos; solo actúan los aplicables. Minimum/Maximum es longitud en texto y Paragraph, valor en Number y tamaño KB para Maximum de archivo. Usa 20–2000 caracteres en descripción y 500–50000 en presupuesto opcional. Es una respuesta de consulta, no precio ni cobro.
Otros tipos son Phone number, Radio buttons, Checkboxes, Date y Hidden value. Radio elige uno y Checkboxes varios. Los ocultos no son fiables para permisos, estado de pago u otras decisiones fuera del control del visitante.
6. Separa valores y etiquetas visibles
Para Project type, elige Dropdown, clave project_type, obligatorio y Step 1. En Options introduce un valor estable por línea:
branding
website
other
En Copy → EN English, Label Project type, Help text Choose the closest match. y Option labels en el mismo orden:
Brand identity
Website project
Something else
Guarda. El visitante ve Website project; se envía website. Las condiciones comparan el valor guardado, no la traducción. No reordenes una caja sin comprobar la otra; al guardar se emparejan por posición. Una etiqueta vacía muestra el valor original.
Cada idioma habilitado tiene Label, Placeholder, Help text, Error message y Option labels. Rellena el principal y revisa los que ofrezcas. Traducir la página no traduce los registros del complemento. Error message puede sustituir varios errores: debe ayudar tanto con un valor inválido como con uno obligatorio vacío.
7. Haz condicional Current website
Crea Current website como Single-line text obligatorio, clave current_website, Step 1, Maximum 255. Guarda, vuelve a abrir si hace falta y busca When to show this field:
- En Depends on, elige project_type.
- En Condition, elige is.
- En Value, escribe website.
- Help text inglés: Your existing address, or write Not launched yet.
- Selecciona Save.
El controlador debe estar en el mismo paso. Créalo primero y verifica el paso del dependiente antes de elegirlo. También hay is not, has any answer y has no answer; los dos últimos ignoran Value. Evita ciclos y prueba todas las ramas tras cambiar pasos u opciones.
Con JavaScript, Website project muestra la pregunta y restaura su obligatoriedad; otras opciones la ocultan. El servidor vuelve a comprobar: un campo no preguntado no se valida ni guarda aunque se envíe un valor extra. Sin JavaScript se ven todos; el navegador puede exigir un campo condicional aunque la condición del servidor sea falsa. Ofrece una respuesta alternativa como “Not applicable” y pruébala; el servidor descarta esa respuesta no solicitada. Se probó anónimamente y con el formulario mejorado.
Es Single-line text, no una búsqueda automática del sitio. Maximum limita longitud, sin comprobar que la web exista. Not launched yet se permite deliberadamente.
8. Añade un adjunto privado y aceptación
Crea Attach a short brief como File upload, clave brief_file, Step 2, opcional. Pon Maximum 2048, Minimum vacío. Explica documentos y tamaño en Help text inglés y guarda.
Se aplica el menor límite positivo entre instalación, Form Settings del sitio y campo. La instalación probada tiene 10240 KB, sitio y campo reducen a 2048 KB. PHP o el servidor pueden imponer menos. Si falla antes de un error útil, pide revisar esos límites.
Las extensiones se definen en configuración de Forms del host; Options no es una lista permitida de archivos. La política predeterminada admite documentos comunes, imágenes y ZIP, comprobando el tipo de contenido. northstar-brief.txt solo contiene texto ficticio. Los adjuntos usan almacenamiento privado del complemento, no Media Library público, con enlaces autorizados de corta duración.
Añade Consent, clave enquiry_consent, Step 2, Required activado y el texto de aceptación de la tabla como Label. Consent conserva el texto aceptado en la instantánea; Checkboxes genérico no ofrece el mismo registro. Usa un texto acorde al propósito y muestra la información relacionada antes de enviar. Aceptar esta consulta no es suscribirse a un boletín.
9. Coloca Form nativo en una página borrador
Crea Start a studio project en el mismo sitio. Añade título y explicación mediante bloques normales. El texto del ejemplo es Tell us what you have in mind. We review enquiries before arranging any work.
En Main elige Add Block → Form, abre Block Fields, selecciona Project enquiry en Form y Save Block. Abre Preview de la página guardada.
El bloque elige un formulario activo por handle. Si falta, está inactivo, no seleccionado o sin campos, no muestra formulario. Revisa sitio y aceptación de envíos si la lista está vacía.
Esta versión no expone un panel general de título/introducción/botón/éxito para nuevos formularios. Usamos bloques de página y los valores Send y Thank you. Your message has been received. No busques los campos de texto Contact Form dentro de este bloque. El importador conserva por separado los textos importados.
La vista instantánea no admite formularios de complementos; guarda y usa la vista de página guardada. Enviar desde ella crea un envío real. Usa sitio de prueba y datos ficticios. Evita dos instancias del mismo formulario en una página: identificadores y progreso de sesión pertenecen al formulario, no a cada ubicación.
10. Completa los dos pasos como visitante
Abre la vista guardada o la página local revisada. Step 1 of 2 solicita Your name, Email address y Project type. Current website comienza oculto.
Escribe Example visitor, visitor@example.test y elige Website project. Aparece Current website; pon Not launched yet o una dirección ficticia apropiada.
Selecciona Continue. Aparece Step 2 of 2. Aún no se guardó un envío: las respuestas permanecen en sesión hasta el final. Abandonar no es una consulta completada. Cookies y continuidad de sesión deben funcionar.
Introduce al menos 20 caracteres, por ejemplo We are planning a small website for a neighbourhood craft workshop and would like to discuss the structure. Usa presupuesto 2500, archivo ficticio pequeño y aceptación. Back vuelve al paso anterior; revisa respuestas después de cambiar una rama.
Selecciona Send una vez. El éxito normal sustituye el formulario:
Prueba a ritmo humano. Cada paso tiene nueva comprobación temporal; un envío automático demasiado rápido puede mostrar éxito sin registro. El mensaje no demuestra almacenamiento o correo. Busca la consulta exacta en la bandeja.
Antes de abrir al público, prueba otra rama, respuesta obligatoria omitida, presupuesto fuera de rango y archivo no admitido o grande. Sin JavaScript, completa los pasos del servidor y confirma que una respuesta de rama falsa no se guarda.
11. Lee el envío y gestiona su estado
Abre Forms → Submissions del sitio. Elige Project enquiry en Form, luego Apply. Search busca respuestas, Status filtra y Reset limpia filtros. Se muestran fecha, formulario, estado y notificación.
Selecciona Open. Un New pasa a Read al abrirse. Las respuestas usan las etiquetas capturadas entonces y muestran Attachments. Las opciones pueden aparecer como website, valor guardado, en vez de la etiqueta. Consent muestra aceptación registrada con su texto.
Usa Download para el archivo. Requiere autenticación y permiso de envíos además de firma breve. Si caduca, reabre el detalle. No publiques enlaces privados ni capturas de su URL completa.
| Estado | Uso |
|---|---|
| New | Trabajo entrante sin abrir. |
| Read | Abierto, no necesariamente respondido. |
| Replied | Márcalo tras responder realmente por tu canal habitual. |
| Archived | Archivado; no enseña al filtro. |
| Quarantined | Retenido para revisión; acciones suprimidas. |
| Spam | Abuso retenido como spam; acciones suprimidas. |
Tras responder, elige Replied y Save. Cambia estado; no redacta ni envía respuesta. Eliminar es permanente. Descarga lo necesario y sigue tu proceso de retención antes de borrar deliberadamente.
12. Verifica cada resultado de entrega
Busca Delivery. El ejemplo separa Notification y Reply to sender. Mailing list: Skipped corresponde a la acción opcional apagada. La página de origen se muestra aparte.
| Resultado | Significado |
|---|---|
| Sent | Aceptado por el transporte; no demuestra llegada ni lectura. |
| Failed | Intento fallido; revisa detalle, destino o transporte. |
| Skipped | Omitido deliberadamente, por ejemplo desactivado. |
| Not configured | Falta un requisito; el correo log local no es entrega real. |
| Sin intento | No se intentó; revisa almacenamiento, protección y acciones. |
Se guarda antes de ejecutar acciones. Un mal destinatario o fallo de correo no elimina la consulta. Los dos mensajes pueden tener resultados distintos. Configura correo y remitente reales y prueba ambos con buzones controlados. Cambiar estado o ajustes no repite automáticamente el envío original; no hay control de reenvío aquí.
Local protection · last 30 days resume decisiones del sitio. Los sospechosos pueden conservarse mientras se suprimen correo, copias, webhooks y Campaigns. Marca abuso real Spam; restaurar un falso positivo a New, Read o Replied registra corrección. Restaurarlo no significa repetir las acciones suprimidas.
13. Exporta CSV del formulario elegido
Vuelve a Submissions, elige Project enquiry, filtros Status/Search y Apply, después Export CSV. Necesita permiso separado y formulario seleccionado; All forms no define columnas comunes.
Exporta los registros filtrados, ID, fecha, estado y respuestas. Los adjuntos aparecen como nombres, no bytes ni enlaces públicos permanentes. Descárgalos del detalle autorizado.
Los encabezados provienen de la primera instantánea exportada y las filas siguientes se alinean por clave. Si cambió mucho el formulario, verifica columnas: campos nuevos ausentes de esa primera instantánea no se añaden automáticamente. Se usa UTF-8 con BOM para hojas de cálculo.
El CSV ya está fuera del control de acceso CMS. Ábrelo con importación segura del programa, especialmente con texto no confiable. Contrasta filas, una respuesta conocida y nombre del archivo con la bandeja antes de usarlo.
14. Importa un Contact Form nativo existente
En su sitio abre Forms → Import Contact Form, localiza la página y pulsa Import una vez. Incluye borradores; la captura muestra uno.
Crea un formulario con cuatro preguntas, idiomas disponibles, título/introducción/botón/éxito, consentimiento y notificación. Lee las notas. El destinatario heredado sigue heredado y la notificación apagada sigue apagada. El consentimiento faltante puede rellenarse desde el idioma principal: revísalo. El importado almacena aunque el bloque antiguo indicara no guardar.
El original sigue intacto y funcionando; Contact Messages permanece separado. Revisa campos, textos, consentimiento y entrega y sustituye el bloque en un borrador o actualización preparada. Importar no cambia la página pública. Repetir crea otro formulario en lugar de actualizar la primera copia.
15. Añade integraciones opcionales conscientemente
Para otro sistema, abre Webhooks, introduce Endpoint URL, configura Signing secret privado, activa y guarda. El receptor debe entender JSON firmado del complemento. Usa un destino HTTPS público controlado; red privada y HTTP inseguro se bloquean por defecto. Mantén secretos fuera de textos, imágenes y notas compartidas.
Puede haber varios webhooks. Vaciar URL elimina la acción, conservando entregas previas. Dejar vacío el secreto existente lo conserva. Verifica resultados individuales y receptor; guardar URL no prueba integración. Esta guía no envía a un destino externo.
Para boletín instala y activa WebBlocks Campaigns compatible, prepara correo/lista y usa Mailing list → Offer a newsletter subscription. Requiere email utilizable y Consent aceptado. Revisa cuál utiliza: la aceptación de esta consulta no pide marketing. Usa un formulario dedicado con texto explícito en lugar de activar sin cambios este ejemplo.
Pon List id solo para una lista concreta; vacío usa el predeterminado del sitio. Los nombres opcionales se asignan por clave de campo. Campaigns envía confirmación que el visitante debe aceptar; la acción no omite doble opt-in. Si falta o está apagado, la consulta puede funcionar y la acción indicar Not configured. No afirmes suscripción sin probar confirmación real.
16. Mantén formulario y retención
Desmarca Accepting submissions para pausar. Las páginas ya no muestran formulario: prepara una alternativa útil. Eliminar uno con envíos lo desactiva preservando historial; sin envíos puede borrarse.
Cambiar etiquetas, tipos y orden afecta a nuevos visitantes; los antiguos conservan instantáneas. Eliminar un campo deja de preguntarlo sin borrar respuestas previas. Las claves existentes quedan fijas tras recibir envíos. Reprueba condiciones, columnas e idiomas después de cambios estructurales.
Configura Delete submissions after (days) en el formulario cuando hayas decidido el periodo real. Por defecto no hay ventana. El administrador debe simular:
php artisan webblocks-forms:prune-submissions --dry-runTras revisar, programa el comando real mediante scheduler del host o cron:
php artisan webblocks-forms:prune-submissionsTener el scheduler Laravel funcionando no programa este comando: añade su tarea. Procesa formularios distintos, por lo que hay que revisar todas las ventanas antes. Elimina adjuntos con envíos caducados y archivos temporales abandonados. Un flujo incompleto puede tener bytes temporales sin registro final.
Solución de problemas
| Síntoma | Comprueba primero |
|---|---|
| Falta Forms | Complemento activo compatible, base, permisos y sitio. |
| Continue/Send falla tras ZIP | Proveedor del host, configuración y limitador con nombre. |
| Selector vacío | Sitio de la página, formulario activo y contexto. |
| No aparece formulario | Handle, Accepting submissions, campos, guardado y activación. |
| No aparece Current website | Mismo paso, valor website exacto, condición y JavaScript. |
| Campo oculto obligatorio bloquea | Condición, script y página guardada; el servidor también resuelve la rama. |
| Continue vuelve al paso | Validación, sesión/cookies, tiempo y paso esperado. |
| Éxito sin registro | Sitio/filtro, almacenamiento, paso final y protección/tiempo. |
| Correo Not configured | Transporte, destinatario y Email address para la copia. |
| Retención del sitio no afecta | Configura el Handling del propio formulario. |
| Archivo rechazado | Contenido/extensión, máximos campo/sitio/host y límites PHP/servidor. |
| Descarga privada falla | Caducidad, autenticación/permiso, sitio y archivo. |
| Faltan columnas CSV | Formulario/filtro y esquema de la primera instantánea exportada. |
| Boletín sin efecto | Campaigns activo, sitio/lista, email y consentimiento explícito aceptado. |
| Etiquetas antiguas en registros | Es normal: la instantánea conserva lo preguntado. |
Comprobación final antes del lanzamiento
Verifica instalación, proveedor y roles, handle, almacenamiento, ambos destinos, tipos, obligatoriedad, etiquetas, condiciones, archivos y aceptación. Completa ramas a ritmo normal, encuentra registros, descarga adjunto y contrasta CSV.
Prueba visitante anónimo, teléfono y sin JavaScript. Confirma correo real aparte, integraciones y simulación de retención. Publica después de estos controles y repite la prueba directa en el HTTPS público y cada idioma ofrecido.
Continúa con referencia de Forms, guía Contact Form, Publicar una página, Menús de navegación o Roles y permisos.