Defining tokens with hook_token_info()for Drupal 8 , 9 , 10 , and 11

Tokens in Drupal provide a powerful system for inserting dynamic content into text areas, making them a versatile tool for module development. This lesson dives into defining custom tokens in Drupal using the hook_token_info(), an essential step to leverage Drupal's token system in your projects.

Understanding the Token System

The token system in Drupal generates dynamic placeholders for various data elements. Once defined, these tokens are replaced with corresponding values, allowing for a flexible way to incorporate dynamic data into content and configuration.

The Role of hook_token_info()

hook_token_info() is a Drupal hook that lets you define new sets of tokens and describe each token. By implementing this hook, you inform Drupal about the available tokens your module provides, making them accessible for use in other areas of your site.

Implementing hook_token_info()

Consider creating a custom module, example_token. We'll add new tokens related to user information. Follow these steps to implement hook_token_info():

<?php
/**
 * Implements hook_token_info().
 */
function example_token_token_info() {
    $info = [];

    // Token type definition
    $info['tokens']['example'] = [
        'name' => t('Example Tokens'),
        'description' => t('Tokens related to example module.'),
    ];

    // Define specific tokens
    $info['tokens']['example']['username'] = [
        'name' => t('Username'),
        'description' => t('The name of the current user.'),
    ];
    $info['tokens']['example']['user_email'] = [
        'name' => t('User Email'),
        'description' => t('The email address of the current user.'),
    ];

    return $info;
}
?>

Explanation of Implementation

• Token Type: Define a new type example representing your module-specific tokens for clearer organization.
• Token Definitions: Each specific token (e.g., username) is defined with a name and description, both wrapped in the t() function for translation.
• Function Return: Return the populated $info array, ensuring it contains structured token data for Drupal to process.

Registering the Hook

Once hook_token_info() is implemented, your module will expose these defined tokens. Ensure your hook is correctly listed and accessible by clearing the cache for the token discovery to take effect:

drush cache-rebuild

Testing Your Tokens

You can test the availability of your new tokens in any configurable text field that supports tokens. For example, within a block configuration, attempt to display a message using the token pattern [example:username].

• Ensure the Token module is enabled, as it provides the user interface for testing these tokens.
• Verify that your tokens are appearing with appropriate descriptions in the token browser available in text editors.

Best Practices

• Clarity in Descriptions: Ensure the token names and descriptions are clear to facilitate easier understanding and adoption by end-users.
• Translations: Use the t() function for all user-visible strings to support localization.
• Organization: Organize tokens logically under meaningful token types to avoid clutter and confusion.

Conclusion

By defining custom tokens via hook_token_info(), you've expanded your module's capability, allowing it to dynamically embed user-specific information seamlessly. This introductory step in token management will serve as a foundation for further enhancements to your module's integration and interaction capabilities.

Looking Ahead

In our next lesson, we'll implement hook_tokens() to handle token replacements, providing the logic required to substitute token placeholders with real data. Stay tuned to learn how to bring your tokens to life!