Lemuel Santos 23 Jan, 2024
Custom Tokens: Extending the Drupal Super Flexible Token System

If you have been involved in Drupal Development or Drupal Site Building for an extended period, you likely have experience working with Drupal's flexible and powerful tokens. In summary, the Drupal token system is a mechanism that enables users to insert dynamic data placeholders, called tokens, into various content areas throughout a Drupal site. These tokens serve as variables that are replaced with actual data when the content is rendered.

Let's explore a quick example… Suppose you want the pages of your site (nodes) to display the teaser image in the Twitter Cards without entering the image URL for each page. You would use a token as depicted in the image below: [node:field_teaser_image:entity:url] - then Drupal would do its magic and output similar to <meta property="og:image" content="[mysite.url]/sites/default/files/2024-01/image-name.jpg" /> within the context of Meta Tags. However, it's essential to note that Drupal tokens are versatile and find applications in various contexts, including default values for Fields, Users, Page Titles, Email templates, and more.

Image URL Example

Another example of tokens being employed in an Email template:

Hi [current-user:name],

Welcome to the Higher Education Portal. 
Click here: [current:user-login-link], to access the introduction of your upcoming course.
Also, read the following page [node:title] to get yourself familiarized with our Education portal.

If your name is Georgia… that first line would result in something like the following

Hi Georgia,

Welcome to the Higher Education Portal.
Click here: https://myhighereducation.site/my-course-login, to access the introduction of your upcoming course.
Also, read the following page https://myhighereducation.site/first-steps to get yourself familiarized with our Education portal.

What if you find yourself wanting to extend beyond the basic tokens provided by Drupal core? It's simple—just install the Token module, and you'll discover a vast array of tokens that will provide basic and advanced needs on your Drupal site. However, as you might have anticipated, there are situations where the existing tokens won't cover everything. After all, what's the point of having everything predefined when you also want to implement some custom code, right? This is where the need for custom tokens arises, especially in complex cases where very specific values are required.

Consider a scenario in which we need to retrieve the value of the latest course instance (session) associated with a specific course. This information is crucial for displaying it as the 'startDate' in the educationEvent metatag (https://schema.org/startDate).

Ready to dive into creating your custom tokens? Here's the process: First, using hook_token_info, we inform Drupal about the new tokens we want it to display. Then, employ hook_tokens to replace the placeholder with the custom value that will populate it. Let's get started!

Now, when you click on the "Browse available tokens" link in any context, whether it's  Blocks, Fields, Email Templates, or MetaTags, as in our case, your new custom tokens should be readily available for you. Beautiful, right?

Available Tokens Screenshot

And with that, dear reader, you'll witness an output similar to this:

As you can see, there are instances where going the extra mile and creating custom tokens becomes essential to precisely showcase the data you want in your Drupal website. If you require assistance in implementing custom tokens, reach out to us. We are here to help you enhance the functionality and customization of your Drupal experience.