Better Field Descriptions
Permite a los usuarios agregar descripciones personalizables y tematizables a los campos de formulario en todos los tipos de entidad sin requerir permisos de gestión de campos.
better_field_descriptions
Install
composer require 'drupal/better_field_descriptions:^2.0'
composer require 'drupal/better_field_descriptions:8.x-1.7'
Overview
Better Field Descriptions proporciona una solución potente para agregar texto de ayuda personalizado y tematizable a los campos de formulario en Drupal. A diferencia de las descripciones de campo estándar que requieren permisos de gestión de campos para editarlas, este módulo separa las responsabilidades: los administradores del sitio pueden seleccionar qué campos deben tener mejores descripciones, mientras que los gestores de contenido o editores pueden escribir y gestionar el texto de descripción por sí mismos.
El módulo soporta todos los tipos de entidad (nodes, términos de taxonomía, usuarios, etc.) y funciona con cualquier tipo de campo. Las descripciones pueden posicionarse encima del campo, debajo del campo, o entre la etiqueta del campo y el elemento de entrada. Cada descripción puede tener su propia etiqueta, o usar una etiqueta predeterminada a nivel de sitio.
Las descripciones se renderizan a través de plantillas Twig, proporcionando flexibilidad total de tematización. El módulo incluye dos plantillas incorporadas: una visualización de texto simple y un envoltorio de fieldset plegable. Los desarrolladores pueden crear plantillas personalizadas que serán descubiertas automáticamente y estarán disponibles en la configuración.
Features
- Agregar descripciones personalizadas a cualquier campo en cualquier tipo de entidad (nodes, términos de taxonomía, usuarios, media, etc.)
- Posicionar descripciones encima del campo, debajo del campo, o entre el título y el elemento de entrada
- Asignar etiquetas personalizadas a cada descripción o usar una etiqueta global predeterminada
- Salida completamente tematizable mediante plantillas Twig con dos opciones incorporadas: texto plano y fieldset plegable
- Permisos separados para selección de campos (admin) y autoría de descripciones (gestores de contenido)
- Funciona con todos los tipos de campo incluyendo carga de archivos, áreas de texto, referencias a entidades y más
- Maneja automáticamente pseudo-campos como el campo de título
- Auto-descubrimiento de plantillas: las plantillas personalizadas colocadas en la carpeta del theme están disponibles automáticamente
- Soporte de indicador de campo requerido en las plantillas de descripción
Use Cases
Texto de Ayuda de Campos Amigable para el Cliente
Una agencia web construye un sitio Drupal para un cliente. El cliente quiere personalizar las descripciones de los campos para que coincidan con sus directrices editoriales, pero la agencia no quiere darles acceso a la configuración de campos. Con Better Field Descriptions, la agencia selecciona los campos en la pestaña Settings, luego otorga al cliente el permiso 'Add Better Descriptions To Selected Fields'. El cliente ahora puede escribir su propio texto de ayuda sin arriesgar cambios accidentales en la configuración de campos.
Ayuda Contextual en Tipos de Contenido Complejos
Un sitio tiene tipos de contenido con muchos campos donde los autores de contenido necesitan orientación. Usando la opción de posición 'Entre título y entrada', los administradores pueden colocar instrucciones detalladas directamente debajo de cada etiqueta de campo pero encima de la entrada, haciendo el texto de ayuda más prominente que las descripciones de campo estándar de Drupal que aparecen debajo de la entrada.
Documentación de Ayuda Plegable
Para campos que requieren documentación extensa (formatos aceptables, directrices, ejemplos), use la plantilla fieldset para envolver las descripciones en un elemento plegable. Esto mantiene los formularios limpios mientras hace disponible la ayuda detallada bajo demanda.
Etiquetado Consistente en Formularios
Establezca una etiqueta predeterminada como 'Directrices' o 'Ayuda' que se aplique a todas las descripciones, creando un patrón de interfaz consistente en todo el sitio. Anule con etiquetas personalizadas para campos específicos cuando sea necesario.
Mover Descripciones Existentes
A veces la posición predeterminada de la descripción (debajo de la entrada) no es ideal. Al habilitar un campo para mejores descripciones pero dejando el texto de descripción vacío, el módulo usará la descripción original del campo pero le permitirá reposicionarla encima del campo o entre la etiqueta y la entrada.
Plantilla Personalizada para Branding
Cree un archivo de plantilla personalizado (ej. better-field-descriptions-branded.html.twig) en la carpeta de plantillas de su theme. El módulo lo auto-descubre y lo hace disponible en el menú desplegable de plantillas. Use esto para estilizar descripciones con el sistema de diseño de su sitio, iconos o requisitos de marcado específicos.
Tips
- Siempre habilite los tipos de entidad en la pestaña Entities primero, luego seleccione campos en Settings, luego agregue descripciones en Bundles - las pestañas deben usarse en este orden
- La posición 'Entre título y entrada' puede causar etiquetas duplicadas con algunos tipos de campo - siempre revise sus formularios después de guardar
- Deje el campo de descripción vacío para reposicionar la descripción original del campo sin cambiar su texto
- Las plantillas personalizadas en la carpeta de plantillas de su theme son auto-descubiertas - nómbrelas better-field-descriptions-*.html.twig
- Los usuarios necesitan tanto el permiso del módulo COMO el permiso 'Use the administration pages and help' para acceder a las páginas de configuración
- Los cambios de plantilla activan una reconstrucción del registro de themes que puede impactar brevemente el rendimiento del sitio
- Para campos de archivo/imagen, el módulo ajusta automáticamente las posiciones de prefijo/sufijo para funcionar correctamente con el widget managed_file
Technical Details
Admin Pages 3
/admin/config/content/better_field_descriptions
La página principal de configuración donde los administradores seleccionan qué campos en todos los tipos de entidad y bundles configurados deben tener mejores descripciones habilitadas. Los campos están organizados por tipo de entidad y bundle en secciones plegables. Marcar un campo aquí lo hace disponible para edición de descripciones en la pestaña Bundles.
/admin/config/content/better_field_descriptions/bundles
La página de edición de descripciones donde los usuarios con el permiso apropiado pueden escribir y configurar el texto de descripción real para cada campo habilitado. Aquí es donde los gestores de contenido agregan orientación útil para los autores de contenido.
/admin/config/content/better_field_descriptions/entities
Página de configuración para seleccionar qué tipos de entidad deben estar disponibles para mejores descripciones de campo. Solo los tipos de entidad habilitados aquí aparecerán en la página principal de Settings para la selección de campos.
Permissions 2
Hooks 3
hook_field_widget_form_alter
El módulo implementa este hook para inyectar mejores descripciones en los widgets de campo durante el renderizado del formulario. Verifica si el campo actual tiene una mejor descripción configurada, luego agrega la descripción renderizada en la posición apropiada del elemento del formulario.
hook_theme
Registra el theme hook better_field_descriptions con archivo de plantilla y ruta configurables. Permite que las plantillas personalizadas sean descubiertas desde el theme activo.
hook_help
Proporciona texto de ayuda para la página de ayuda del módulo en /admin/help/better_field_descriptions.