Custom Tokens

Allows site administrators to create custom tokens with user-defined content that can be used throughout the Drupal site via the Token API.

token_custom
6,245 sites
22
drupal.org
gui api content
token replacement placeholder custom content reusable content text snippets content management
Drupal 10 Drupal 11

Install

Drupal 11, 10 v8.x-1.0
composer require 'drupal/token_custom:8.x-1.0'

Overview

The Custom Tokens module provides a complete administrative interface for creating and managing custom tokens within Drupal. Tokens are reusable placeholders that get replaced with dynamic content when processed, and this module extends the Token API by allowing users to define their own custom tokens without writing any code.

Custom tokens are organized into types (categories), enabling logical grouping of related tokens. Each token contains formatted text content that supports any text format available on the site, including filtered HTML. The module fully supports translation, allowing token names, descriptions, and content to be translated into multiple languages.

When a custom token is used in content or configuration fields that support token replacement, the module automatically substitutes the token placeholder with its defined content. This makes it ideal for managing reusable text snippets, contact information, legal disclaimers, or any other content that needs to appear consistently across multiple locations.

Features

  • Create custom token types (categories) to organize tokens logically
  • Define custom tokens with machine names for use in token-enabled fields
  • Support for formatted text content using any available text format (Plain text, Basic HTML, Full HTML, etc.)
  • Full translation support for token descriptions and content through Drupal's translation system
  • Automatic integration with Drupal's Token API via hook_token_info() and hook_tokens()
  • Cache-aware implementation with automatic cache invalidation when tokens are created, updated, or deleted
  • Permission-based access control for viewing, creating, editing, and deleting tokens and token types
  • Administrative listing pages with operations for managing tokens and types
  • Protection against deleting token types that are in use by existing tokens

Use Cases

Reusable Contact Information

Create tokens for company contact details like address, phone number, and email. Use tokens like [custom:company-address] and [custom:support-email] throughout the site. When contact information changes, update the token in one place and it updates everywhere automatically.

Legal Disclaimers and Boilerplate Text

Store legal disclaimers, copyright notices, or terms of service snippets as tokens. Insert [custom:copyright-notice] or [custom:privacy-disclaimer] into content types, blocks, or email templates to ensure consistent legal text across the site.

Dynamic Content Snippets

Create tokens for frequently changing content like promotional messages, seasonal greetings, or campaign codes. Content editors can update [custom:promo-message] token content without touching the pages where it appears.

Multilingual Content Tokens

On multilingual sites, create tokens with translated content for each language. The module automatically serves the correct translation based on the current language context, ensuring [custom:welcome-message] displays appropriately in English, Spanish, French, etc.

Organized Token Categories

Create custom token types to organize tokens by purpose: 'company' for business info ([company:address], [company:hours]), 'legal' for legal text ([legal:terms], [legal:privacy]), 'promo' for marketing ([promo:current-offer]). This improves discoverability in token browsers.

Email Template Variables

Use custom tokens in email templates configured with modules like Webform or Commerce. Tokens like [custom:email-footer] or [custom:support-hours] can be consistently used across all email communications and updated centrally.

Tips

  • Use descriptive machine names for tokens that indicate their purpose, such as 'company-phone' rather than 'phone1'
  • Create multiple token types to organize tokens logically - for example, separate types for 'contact', 'legal', and 'marketing' content
  • Remember that token content supports text formats, so you can include formatted HTML, links, and other rich content
  • The Token module provides a token browser that shows all available custom tokens - access it through fields that support tokens
  • When updating a token's content, changes take effect immediately after cache clearing - no need to re-save content using that token
  • Custom tokens work anywhere the Token module is integrated, including Pathauto patterns, Metatag values, Webform emails, and more
  • For multilingual sites, translate token content through the standard translation workflow to maintain consistent messaging across languages

Technical Details

Admin Pages 8
Custom tokens /admin/structure/token-custom

Lists all custom tokens defined on the site. From this page you can view, edit, and delete existing tokens, as well as add new tokens. The listing shows the machine name, type, name, description, and raw content for each token.

Add custom token /admin/structure/token-custom/add

Create a new custom token. If multiple token types exist, you will first select which type the token should belong to. The token can then be used in any token-enabled field using the format [type:machine-name].

Edit custom token /admin/structure/token-custom/manage/{token_custom}/edit

Edit an existing custom token. The machine name cannot be changed after creation to prevent breaking existing token references.

Delete custom token /admin/structure/token-custom/manage/{token_custom}/delete

Confirmation page for deleting a custom token. Deleting a token will cause any content using that token to display the raw token placeholder instead of the replacement content.

Custom token types /admin/structure/token-custom/type

Lists all custom token types (categories) defined on the site. Token types provide namespaces for organizing tokens. A default 'Custom' type is provided upon installation.

Add custom token type /admin/structure/token-custom/type/add

Create a new token type to organize custom tokens. The machine name becomes the token namespace prefix, e.g., creating a type with machine name 'company' allows tokens like [company:address].

Edit custom token type /admin/structure/token-custom/type/manage/{token_custom_type}/edit

Edit an existing token type's name and description. The machine name cannot be changed after creation.

Delete custom token type /admin/structure/token-custom/type/manage/{token_custom_type}/delete

Confirmation page for deleting a token type. Types that have tokens assigned to them cannot be deleted - you must first delete or reassign all tokens using that type.

Permissions 3
Access the custom tokens overview page

Allows users to view the custom tokens listing page. Required in combination with 'administer custom tokens' to access the tokens overview.

Administer custom tokens

Allows users to create, edit, and delete custom tokens. This is a restricted permission that should only be granted to trusted roles as tokens can contain HTML content.

Administer custom token types

Allows users to create, edit, and delete custom token types (categories). This is a restricted permission as it affects the organization of all custom tokens.

Hooks 2
hook_token_info

Registers custom token types and tokens with the Token API. This hook is implemented to expose all TokenCustomType entities as token types and all TokenCustom entities as available tokens within their respective types.

hook_tokens

Provides the actual replacement values for custom tokens. When a token is being replaced, this hook loads the corresponding TokenCustom entity and returns its formatted content. Handles translation and adds appropriate cache metadata.

Troubleshooting 5
Custom token is not being replaced and shows as raw text like [custom:my-token]

Clear all caches using drush cr or Administration > Configuration > Performance > Clear all caches. Verify the token machine name matches exactly (case-sensitive). Ensure the field or context supports token replacement.

Cannot delete a token type

Token types cannot be deleted if any tokens belong to that type. First delete all tokens using that type, or edit the tokens to assign them to a different type, then delete the type.

Tokens not appearing in token browser

Clear the site cache and the static token cache. The module implements cache invalidation but manual cache clearing may be needed. Verify the token type and token are both enabled.

Token content shows HTML tags instead of formatted output

Ensure the token content has the correct text format selected. If the token was created with 'Plain text' format, HTML will be escaped. Edit the token and select an appropriate format like 'Basic HTML' or 'Full HTML'.

Cannot create tokens - form is blank or shows error

At least one token type must exist to create tokens. If the default 'Custom' type was deleted, create a new token type first at Administration > Structure > Custom tokens > Custom Token Types > Add Token Type.

Security Notes 4
  • The 'administer custom tokens' permission is marked as restricted because tokens can contain HTML content that gets rendered on the site. Only grant this permission to trusted roles.
  • Token content respects text format permissions. Users creating tokens can only use text formats they have access to.
  • Be cautious about what content you store in tokens, as tokens may be displayed to anonymous users depending on where they are used.
  • The 'administer custom token types' permission is restricted as it affects the organization of all custom tokens on the site.