Clientside Validation
Añade validación de formularios del lado del cliente a los formularios de Drupal utilizando atributos de datos y el jQuery Validation Plugin.
clientside_validation
Instalar
composer require 'drupal/clientside_validation:^4.1'
Overview
Clientside Validation es un módulo que proporciona validación instantánea de formularios del lado del cliente para formularios de Drupal antes de enviarlos al servidor. El módulo funciona añadiendo atributos de datos HTML5 a los elementos del formulario, que luego son procesados por una biblioteca de validación JavaScript.
El módulo consiste en un módulo base principal y un submódulo jQuery. El módulo principal maneja el lado PHP añadiendo atributos data-rule-* y data-msg-* a los elementos del formulario según sus requisitos de validación. El submódulo clientside_validation_jquery integra el popular jQuery Validation Plugin para realizar la validación real del lado del cliente.
El módulo soporta varios tipos de validación incluyendo campos obligatorios, validación de correo electrónico, validación de URL, validación de rango numérico (min, max, step), coincidencia de patrones y verificación de igualdad de campos. También se integra perfectamente con la API States de Drupal para validación condicional, CKEditor para campos WYSIWYG y el módulo Inline Form Errors para una visualización consistente de errores.
Features
- Validación automática del lado del cliente para todos los formularios de Drupal sin configuración adicional
- Arquitectura basada en plugins que permite validadores personalizados a través del sistema de plugins CvValidator
- Validadores integrados para required, email, URL, min, max, step, maxlength y validación de patrones
- Soporte para campos condicionalmente obligatorios usando la API States de Drupal (#states)
- Mensajes de error personalizados mediante las propiedades #required_error, #email_error, #url_error, #min_error, #max_error, #step_error, #maxlength_error y #pattern_error de los elementos del formulario
- Validación equal-to para confirmación de contraseñas y escenarios similares de coincidencia de campos
- Soporte de validación de formularios AJAX con comportamiento configurable
- Integración con CKEditor para validar contenido del editor WYSIWYG
- Integración con el módulo Inline Form Errors para estilos de error consistentes
- Carga flexible de bibliotecas vía CDN o instalación local
- Comandos Drush para gestionar la biblioteca jQuery Validation
- Sistema de hooks para controlar el comportamiento de validación y extender funcionalidades
Use Cases
Validación básica de campo obligatorio
Añade la propiedad #required a cualquier elemento de formulario para obtener automáticamente validación obligatoria del lado del cliente. El módulo mostrará un mensaje de error como 'El campo nombre del campo es obligatorio.' cuando el usuario intente enviar sin completar el campo. Personaliza el mensaje usando la propiedad #required_error.
Validación de confirmación de contraseña
Usa la propiedad #equal_to para validar que un campo de confirmación coincida con otro campo. Por ejemplo, añade '#equal_to' => 'pass1' a un campo de confirmación de contraseña para asegurar que coincida con el campo de contraseña original llamado 'pass1'. Personaliza el mensaje de error con #equal_to_error.
Validación basada en patrones
Usa la propiedad #pattern con una expresión regular para validar formatos de campo como números de teléfono, códigos postales o identificadores personalizados. Ejemplo: '#pattern' => '[789][0-9]{9}' para números de teléfono de India. Personaliza el mensaje de error con #pattern_error.
Validación de rango numérico
Usa las propiedades #min, #max y #step en campos numéricos para validar restricciones numéricas. Por ejemplo, campos de edad pueden usar '#min' => 18, '#max' => 120, y campos de cantidad pueden usar '#step' => 5 para permitir solo múltiplos de 5.
Validación de formularios AJAX
Habilita 'Validar todos los formularios antes del envío AJAX' en la configuración o añade la clase CSS 'cv-validate-before-ajax' a formularios específicos para validar campos antes de que ocurran los envíos de formularios AJAX, previniendo solicitudes innecesarias al servidor.
Campos condicionalmente obligatorios con la API States
Combina la API #states de Drupal con validación del lado del cliente para campos condicionalmente obligatorios. Ejemplo: '#states' => ['required' => [':input[name="option"]' => ['value' => 'other']]] hará un campo obligatorio solo cuando otro campo tenga un valor específico.
Creación de validadores personalizados
Extiende el módulo creando plugins CvValidator en tu módulo personalizado. Coloca la clase del plugin en src/Plugin/CvValidator/ con la anotación @CvValidator especificando tipos/atributos soportados. Implementa getRules() para devolver reglas de validación y mensajes.
Tips
- Usa el módulo demo (clientside_validation_demo) para probar todas las funciones de validación y ver ejemplos funcionales de configuraciones de elementos de formulario.
- Para una mejor experiencia de usuario, habilita 'Validar en Blur/focusout' en la configuración para proporcionar retroalimentación inmediata mientras los usuarios navegan por los campos del formulario.
- Al crear validadores personalizados, implementa hook_clientside_validation_validator_info_alter() para adjuntar cualquier biblioteca JavaScript adicional que tu validador requiera.
- El módulo soporta automáticamente los stream wrappers de Drupal (public://, private://) en la validación de URL, permitiendo referencias de archivo válidas.
- Usa hook_clientside_validation_should_validate() para deshabilitar selectivamente la validación para formularios o elementos específicos que requieran manejo especial.
- JavaScript personalizado puede escuchar el evento 'cv-jquery-validate-options-update' en document para modificar las opciones de jQuery Validation globalmente.
- Para formularios con el atributo formnovalidate en botones de envío, la validación del lado del cliente se omitirá, útil para botones 'Cancelar' o 'Guardar como borrador'.
Technical Details
Admin Pages 2
/admin/config/user-interface/clientside-validation-jquery-settings
Configura cómo se carga el jQuery Validation Plugin y cómo se comporta la validación en los formularios. Esta página permite a los administradores elegir entre carga de biblioteca CDN y local, configurar el comportamiento de validación de formularios AJAX y habilitar funciones de validación adicionales.
/admin/config/user-interface/clientside-validation-demo
Un formulario de demostración que muestra todas las capacidades de validación del módulo Clientside Validation. Este formulario incluye ejemplos de campos obligatorios, mensajes de error personalizados, campos condicionalmente obligatorios, validación de email, validación de URL, validación numérica con min/max/step, coincidencia de patrones y validación de igualdad de campos.
Hooks 2
hook_clientside_validation_validator_info_alter
Permite a los módulos alterar las definiciones de plugins CvValidator. Puede usarse para añadir bibliotecas JavaScript personalizadas, modificar tipos de elementos soportados o cambiar el comportamiento del plugin.
hook_clientside_validation_should_validate
Permite a los módulos controlar si un elemento de formulario específico debe recibir validación del lado del cliente. Devuelve FALSE para omitir la validación de un elemento.
Drush Commands 3
Muestra si la biblioteca jQuery Validation está instalada localmente en el directorio /libraries.
Descarga e instala la biblioteca jQuery Validation en /libraries/jquery-validation. Extrae y renombra automáticamente el archivo descargado.
Elimina la biblioteca jQuery Validation instalada localmente de /libraries/jquery-validation.
Troubleshooting 6
Verifica si la biblioteca está cargada inspeccionando el código fuente de la página buscando jquery.validate.min.js. Si usas biblioteca local, ejecuta 'drush cvjls' para verificar el estado de instalación. Si no está instalada, habilita CDN en la configuración o ejecuta 'drush cvjld' para descargar.
Asegúrate de que la URL del CDN sea accesible desde tu servidor. El módulo valida la URL verificando si jquery.validate.min.js es accesible en la ruta especificada. Usa el formato: https://cdn.jsdelivr.net/npm/jquery-validation@1.21.0/dist/
Establece 'Validar todos los formularios antes del envío AJAX' en 'Sí' en la configuración, o añade la clase CSS 'cv-validate-before-ajax' a los formularios que deben validarse antes del envío AJAX.
Asegúrate de que el módulo ckeditor esté habilitado. La biblioteca de integración se carga automáticamente cuando CKEditor está presente. Si aún no funciona, verifica la consola del navegador en busca de errores de JavaScript.
Habilita el módulo Inline Form Errors para obtener un estilo consistente entre los mensajes de error de validación del lado del cliente y del lado del servidor.
Asegúrate de usar el nombre de propiedad correcto para errores personalizados. Cada validador tiene su propia propiedad de error: #required_error, #email_error, #url_error, #min_error, #max_error, #step_error, #maxlength_error, #pattern_error, #equal_to_error, #url_internal_external_error.