Token Filter
Un módulo de filtro de texto que reemplaza tokens globales y de entidad con sus valores reales en campos de texto formateados.
token_filter
Install
composer require 'drupal/token_filter:^2.2'
composer require 'drupal/token_filter:^2.1'
Overview
Token Filter es un módulo sencillo que integra el sistema de tokens de Drupal con los formatos de texto. Proporciona un filtro de entrada que reemplaza automáticamente los marcadores de tokens (como [site:name] o [node:title]) con sus valores correspondientes cuando se renderiza el contenido.
El módulo funciona perfectamente con el módulo Token para proporcionar un navegador de tokens dentro de CKEditor 5, permitiendo a los editores de contenido explorar e insertar fácilmente los tokens disponibles directamente desde la interfaz del editor WYSIWYG. El filtro soporta tanto tokens globales (valores de todo el sitio como nombre del sitio, fecha actual) como tokens específicos de entidad (título del node, nombre del autor, etc.).
Al editar contenido, los tokens permanecen como marcadores en el texto almacenado, siendo reemplazados con valores reales solo en el momento del renderizado. Esto asegura que el contenido dinámico se mantenga actualizado automáticamente.
Features
- Filtro de texto que reemplaza tokens globales (nombre del sitio, fecha actual, usuario actual, etc.) con sus valores en el momento del renderizado
- Reemplazo de tokens de entidad que soporta tokens contextuales de la entidad actual que se está visualizando (título del node, autor, etc.)
- Integración del navegador de tokens en la barra de herramientas de CKEditor 5 que permite a los editores de contenido explorar e insertar tokens directamente en el editor WYSIWYG
- Manejo configurable de tokens vacíos - elige si dejar los tokens no reemplazables tal como están o eliminarlos de la salida
- Soporte de migración automática de CKEditor 4 a CKEditor 5 para configuraciones existentes del botón del navegador de tokens
- Soporte de migración de Drupal 7 a Drupal 10/11 con mapeo automático del ID del filtro de filter_tokens a token_filter
- Integración de consejos de filtro mostrando tokens disponibles con un enlace al navegador de tokens en las páginas de ayuda del formato de texto
Use Cases
Información dinámica del sitio en el contenido
Muestra el nombre del sitio, eslogan o URL dinámicamente en el contenido de la página. Por ejemplo, crea un bloque de pie de página con '[site:name] © [current-date:custom:Y]' que actualiza automáticamente el año y refleja cualquier cambio en el nombre del sitio.
Atribución de autor en artículos
Incluye información del autor en plantillas de artículos usando tokens de entidad como '[node:author:display-name]' o '[node:created:medium]' para mostrar automáticamente quién escribió el contenido y cuándo.
Mensajes personalizados para usuarios
Crea mensajes de bienvenida o contenido específico para usuarios usando tokens del usuario actual como '¡Bienvenido de nuevo, [current-user:display-name]!' en bloques o páginas.
Contenido con referencias cruzadas consistentes
Referencia las propiedades de la página actual en el contenido, como '[node:title]' o '[node:url:absolute]' para crear enlaces autorreferenciales o metadatos que se actualizan automáticamente si el contenido es renombrado.
Contenido basado en plantillas con el navegador de tokens
Los editores de contenido pueden usar el botón del navegador de tokens de CKEditor para insertar fácilmente los tokens disponibles sin necesidad de memorizar la sintaxis de tokens. El navegador muestra todos los tokens disponibles organizados por tipo con descripciones.
Migración desde Drupal 7
Los sitios que migran desde Drupal 7 que usaban el filtro filter_tokens tendrán sus configuraciones de formato de texto actualizadas automáticamente para usar token_filter, preservando la funcionalidad de reemplazo de tokens.
Tips
- Usa tokens globales como [site:name], [current-date:*] y [current-user:*] para contenido que debería funcionar en cualquier lugar independientemente del contexto.
- Los tokens de entidad como [node:*] solo funcionan cuando el filtro de tokens procesa contenido en el contexto de esa entidad siendo renderizada.
- Habilita 'Replace empty values' si quieres una salida limpia sin marcadores de tokens sobrantes, pero deshabilítalo durante el desarrollo para detectar fácilmente tokens mal configurados.
- El navegador de tokens en CKEditor 5 soporta funcionalidad de clic para insertar - simplemente haz clic en un token en el navegador para insertarlo en la posición del cursor.
- Para mejor rendimiento, considera colocar el filtro de tokens temprano en el orden de procesamiento de filtros ya que los tokens pueden afectar cómo otros filtros procesan el contenido.
- Los valores de los tokens se reemplazan en el momento del renderizado, no cuando se guarda el contenido, por lo que los tokens dinámicos como [current-date:*] siempre muestran valores actuales.
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format}
Al editar un formato de texto, los ajustes de Token Filter aparecen en la sección de configuración del filtro. Aquí es donde habilitas el filtro de reemplazo de tokens y configuras su comportamiento.
Hooks 2
hook_preprocess_field
Establece el contexto de la entidad actual para el reemplazo de tokens. Cuando se está renderizando un campo, este hook captura la entidad padre y la almacena en una variable estática para que el filtro de tokens pueda acceder a los tokens específicos de la entidad durante el procesamiento.
hook_migration_plugins_alter
Modifica los plugins de migración para mapear el ID del filtro filter_tokens de Drupal 7 al ID token_filter de Drupal 10/11 durante las migraciones d7_filter_format.
Troubleshooting 5
Asegúrate de que el filtro 'Replaces global and entity tokens with their values' esté habilitado para el formato de texto que se está utilizando. Verifica que el campo de contenido esté usando ese formato de texto.
Los tokens de entidad solo funcionan en el contexto de un campo de entidad renderizado. No funcionarán en bloques u otros contextos donde no se está renderizando ninguna entidad. Usa tokens globales en su lugar para contextos sin entidad.
Edita la configuración del formato de texto y añade el botón 'Token browser' a la barra de herramientas de CKEditor 5. Asegúrate de que los módulos Token Filter y Token estén habilitados.
Este es el comportamiento esperado cuando 'Replace empty values' está deshabilitado. Habilita esta opción en los ajustes del filtro si quieres que los tokens no resolubles se eliminen de la salida.
Configura los ajustes del plugin del navegador de tokens de CKEditor 5 para restringir qué tipos de tokens aparecen. Edita el formato de texto y selecciona tipos específicos de tokens en la configuración del navegador de tokens.
Security Notes 3
- Token Filter usa el tipo de filtro TYPE_TRANSFORM_IRREVERSIBLE, lo que significa que la transformación no puede revertirse - los marcadores de tokens originales se reemplazan en la salida.
- El módulo tiene cobertura oficial de avisos de seguridad de Drupal, indicando que sigue las mejores prácticas de seguridad.
- El reemplazo de tokens ocurre durante el renderizado con manejo adecuado de metadatos de caché mediante BubbleableMetadata para asegurar que el contenido en caché se invalide apropiadamente cuando los valores de los tokens cambian.