Token Filter
A text filter module that replaces global and entity tokens with their actual values in formatted text fields.
token_filter
Install
composer require 'drupal/token_filter:^2.2'
composer require 'drupal/token_filter:^2.1'
Overview
Token Filter is a straightforward module that integrates Drupal's token system with text formats. It provides an input filter that automatically replaces token placeholders (like [site:name] or [node:title]) with their corresponding values when content is rendered.
The module works seamlessly with the Token module to provide a Token Browser within CKEditor 5, allowing content editors to easily browse and insert available tokens directly from the WYSIWYG editor interface. The filter supports both global tokens (site-wide values like site name, current date) and entity-specific tokens (node title, author name, etc.).
When editing content, tokens remain as placeholders in the stored text, only being replaced with actual values at render time. This ensures dynamic content stays up-to-date automatically.
Features
- Text filter that replaces global tokens (site name, current date, current user, etc.) with their values at render time
- Entity token replacement that supports context-aware tokens from the current entity being viewed (node title, author, etc.)
- CKEditor 5 Token Browser toolbar integration allowing content editors to browse and insert tokens directly in the WYSIWYG editor
- Configurable empty token handling - choose whether to leave unreplaceable tokens as-is or remove them from output
- Automatic CKEditor 4 to CKEditor 5 migration support for existing Token Browser toolbar configurations
- Drupal 7 to Drupal 10/11 migration support with automatic filter ID mapping from filter_tokens to token_filter
- Filter tips integration showing available tokens with a link to the token browser on text format help pages
Use Cases
Dynamic Site Information in Content
Display the site name, slogan, or URL dynamically in page content. For example, create a footer block with '[site:name] © [current-date:custom:Y]' that automatically updates the year and reflects any site name changes.
Author Attribution in Articles
Include author information in article templates using entity tokens like '[node:author:display-name]' or '[node:created:medium]' to automatically show who wrote the content and when.
Personalized User Messages
Create welcome messages or user-specific content using current user tokens such as 'Welcome back, [current-user:display-name]!' in blocks or pages.
Consistent Cross-Referenced Content
Reference the current page's properties in content, such as '[node:title]' or '[node:url:absolute]' to create self-referencing links or metadata that updates automatically if the content is renamed.
Template-Based Content with Token Browser
Content editors can use the CKEditor Token Browser button to easily insert available tokens without needing to memorize token syntax. The browser shows all available tokens organized by type with descriptions.
Migration from Drupal 7
Sites migrating from Drupal 7 that used the filter_tokens filter will automatically have their text format configurations updated to use token_filter, preserving token replacement functionality.
Tips
- Use global tokens like [site:name], [current-date:*], and [current-user:*] for content that should work anywhere regardless of context.
- Entity tokens like [node:*] only work when the token filter processes content in the context of that entity being rendered.
- Enable 'Replace empty values' if you want clean output without leftover token placeholders, but disable it during development to easily spot misconfigured tokens.
- The Token Browser in CKEditor 5 supports click-to-insert functionality - just click a token in the browser to insert it at the cursor position.
- For better performance, consider placing the token filter early in the filter processing order since tokens may affect how other filters process the content.
- Token values are replaced at render time, not when content is saved, so dynamic tokens like [current-date:*] always show current values.
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format}
When editing a text format, the Token Filter settings appear in the filter configuration section. This is where you enable the token replacement filter and configure its behavior.
Hooks 2
hook_preprocess_field
Sets the current entity context for token replacement. When a field is being rendered, this hook captures the parent entity and stores it in a static variable so the token filter can access entity-specific tokens during processing.
hook_migration_plugins_alter
Alters migration plugins to map Drupal 7's filter_tokens filter ID to Drupal 10/11's token_filter ID during d7_filter_format migrations.
Troubleshooting 5
Ensure the 'Replaces global and entity tokens with their values' filter is enabled for the text format being used. Check that the content field is using that text format.
Entity tokens only work in the context of a rendered entity field. They won't work in blocks or other contexts where no entity is being rendered. Use global tokens instead for non-entity contexts.
Edit the text format configuration and add the 'Token browser' button to the CKEditor 5 toolbar. Ensure both Token Filter and Token modules are enabled.
This is expected behavior when 'Replace empty values' is disabled. Enable this option in the filter settings if you want unresolvable tokens to be removed from output.
Configure the Token Browser CKEditor 5 plugin settings to restrict which token types appear. Edit the text format and select specific token types in the Token Browser configuration.
Security Notes 3
- Token Filter uses TYPE_TRANSFORM_IRREVERSIBLE filter type, meaning the transformation cannot be reversed - original token placeholders are replaced in the output.
- The module has official Drupal security advisory coverage, indicating it follows security best practices.
- Token replacement happens during rendering with proper cache metadata handling via BubbleableMetadata to ensure cached content is invalidated appropriately when token values change.