Label Help
Añade texto de ayuda directamente debajo de las etiquetas de los campos de formulario, posicionándolo entre la etiqueta y el elemento de entrada.
label_help
Instalar
composer require 'drupal/label_help:8.x-1.0'
Overview
El módulo Label Help proporciona una forma de añadir texto de ayuda a los campos de formulario de Drupal que aparece debajo de la etiqueta del formulario pero encima del elemento de entrada del formulario. Esto es diferente de la descripción de campo estándar de Drupal, que aparece debajo del elemento de formulario.
Este posicionamiento es particularmente útil para proporcionar contexto inmediato o instrucciones que los usuarios deben ver antes de interactuar con un campo de formulario, en lugar de después de que ya hayan comenzado a introducir datos. El módulo funciona con todos los tipos de campo de Field API mediante una lógica de colocación inteligente que maneja varias configuraciones de widgets, incluyendo contenedores, fieldsets, elementos details, checkboxes, radios y campos multivalor.
Label Help se integra perfectamente con Field UI, añadiendo un simple textarea a la configuración de campo donde los administradores pueden introducir el texto de ayuda. Para desarrolladores, también proporciona una propiedad personalizada #label_help de Form API para uso programático y funciona con hook_form_alter() para modificar formularios existentes.
El módulo incluye plantillas especializadas y CSS para los principales temas de administración de Drupal: Seven, Claro y Gin, asegurando una visualización consistente y correctamente estilizada en diferentes interfaces administrativas.
Features
- Añade un textarea 'Mensaje de ayuda de etiqueta' a la configuración de campo en Field UI, permitiendo a los administradores introducir texto de ayuda a través de la interfaz web
- Posiciona el texto de ayuda entre la etiqueta del campo y el elemento de entrada del formulario, proporcionando contexto antes de que los usuarios interactúen con el campo
- Soporta todos los tipos de campo de Field API incluyendo campos de texto, checkboxes, radios, listas de selección, referencias a entidades, fechas, enlaces, archivos, imágenes y más
- Proporciona lógica de colocación especializada manejando más de 18 configuraciones de widgets diferentes, incluyendo contenedores, fieldsets, elementos details y campos multivalor
- Incluye plantillas específicas por tema y CSS para los temas de administración Seven, Claro y Gin con herencia de estilos apropiada
- Proporciona la propiedad #label_help de Form API para añadir texto de ayuda programáticamente en módulos o temas personalizados
- Funciona con hook_form_alter() y hook_FORM_ID_alter() para modificar campos de formulario existentes
- Incluye modos de depuración para solucionar problemas de colocación, mostrando coincidencias de casos de uso y volcados de elementos de Form API
- Complementa la descripción de campo existente de Drupal en lugar de reemplazarla - ambas pueden usarse juntas
Use Cases
Proporcionar contexto inmediato del campo
Usa la ayuda de etiqueta para proporcionar instrucciones esenciales que los usuarios necesitan ver antes de comenzar a introducir datos. Por ejemplo, en un campo 'Número de teléfono', podrías añadir texto de ayuda de etiqueta diciendo 'Introduce el número con código de país, ej., +1 555-123-4567' para que los usuarios conozcan el formato esperado inmediatamente.
Explicar requisitos del campo
Añade ayuda de etiqueta para explicar requisitos o restricciones específicas de un campo que los usuarios deben entender desde el principio. Por ejemplo, en un campo 'Nombre de usuario', la ayuda de etiqueta podría indicar 'Debe tener entre 3-20 caracteres, solo letras y números' haciendo visibles los requisitos antes de la entrada.
Complementar campos complejos
Para widgets de campos multivalor o complejos como referencias a entidades o campos de dirección, usa la ayuda de etiqueta para proporcionar una visión general de lo que el campo está recopilando, mientras usas la descripción estándar debajo para instrucciones detalladas o ejemplos.
Mejora programática de formularios
En módulos o temas personalizados, usa la propiedad #label_help de Form API o hook_form_alter() para añadir texto de ayuda específico del contexto a los formularios. Esto es útil para añadir texto de ayuda dinámico basado en roles de usuario, contenido actual u otras condiciones.
Orientación para editores de contenido
Ayuda a los editores de contenido a entender el propósito y las mejores prácticas para cada campo. Por ejemplo, en un campo 'Meta descripción', la ayuda de etiqueta podría decir 'Resume el contenido de la página en 155-160 caracteres para motores de búsqueda' proporcionando orientación SEO justo donde se necesita.
Tips
- Mantén el texto de ayuda de etiqueta conciso - debe proporcionar contexto rápido, no documentación extensa
- Usa la ayuda de etiqueta para información 'imprescindible antes de introducir' y las descripciones estándar para detalles 'conveniente saber'
- Tanto la ayuda de etiqueta como las descripciones de campo estándar pueden usarse juntas - sirven propósitos complementarios
- El módulo detecta automáticamente el tema de administración activo y aplica el estilo apropiado
- El modo de depuración muestra marcas de verificación (✅) para mensajes colocados exitosamente y muestra el número de caso de uso para solución de problemas
Technical Details
Hooks 2
#label_help
Una propiedad personalizada de Form API que puede añadirse a elementos de formulario para mostrar texto de ayuda debajo de la etiqueta del campo. Esta es la forma programática de añadir texto de ayuda de etiqueta.
hook_form_alter() / hook_FORM_ID_alter()
Los hooks estándar de alteración de formularios de Drupal pueden usarse para añadir #label_help a campos de formulario existentes definidos por otros módulos.
Troubleshooting 3
Habilita el modo de depuración añadiendo $settings['label_help_debug'] = TRUE; en settings.php. Recarga la página del formulario para ver la salida de depuración identificando el tipo de widget de campo y el caso de uso coincidente con la lógica de colocación de Label Help. Si no se detecta ningún caso de uso, verás un mensaje de advertencia.
Habilita el modo de volcado de elementos de Form API añadiendo $settings['label_help_debug_dump'] = TRUE; en settings.php. Esto usa el Variable Dumper de Symfony para proporcionar un volcado navegable del array de elementos de Form API. Nota: esto puede impedir el renderizado completo de la página, lo cual es un comportamiento esperado.
Asegúrate de estar usando uno de los temas de administración soportados: Seven, Claro o Gin. El módulo incluye CSS especializado para estos temas. Para temas personalizados, puede que necesites añadir CSS personalizado dirigido a las clases .description--label-help o .form-item__description--label-help.