Drupal offers a powerful, yet often unsung, core feature called token substitution. With this mechanism, content authors and site administrators can use placeholders to insert dynamic information in many locations, without needing to write custom code or frequently update content.

What are tokens?

In Drupal, a token is a string of text surrounded by square brackets, such as [node:title]. When a page is generated, Drupal modules may perform token substitution on the text, and change it into whatever it stands for.

Tokens can represent lots of kinds of information. There are built-in tokens for global site variables, like the site name and primary e-mail address. There are contextual tokens, like the login name of the current user. And there are utility tokens, such as a random number.

What information can a token provide?

This depends heavily on the token's context. All tokens have access to the global context, which allows information about the whole site (like the main e-mail address) or about the world (like the current date) to be fetched when needed. However some tokens are more specific.

A token like the [node:title] example above raises an obvious question: Which node's title? A token like this one is not even available to be used unless the answer is obvious. When a Drupal module asks for tokens to be replaced, it must provide the context available in the current situation.

For example, let's say we are using the Metatag module and wish to use the node's title as part of the Description meta information for the page. The Metatag module knows that, if it is producing a full page view of a node, tokens relevant to that node may be needed. So, it provides the currently-viewed node as the context when requesting substitutions, and we can then fetch the title.

Some contexts can even be chained. Let's say that we want this description to include the last login date of the author of the current node, for some reason. Even though the author is a user, and there is no information about a user in the current context, we can get the author of the context's node and then use user-based tokens related to that author automatically, like [node:author:last-login:long].

Where are tokens used?

Nearly everywhere! Out of the box, you may notice tokens on the user account settings page, for example:

This interface displays a few token possibilities above the form, but not all of them, and not in the friendliest way. We can easily improve this, however.

Super-charging your tokens

It is practically essential that a Drupal site include the contributed Token module. This module does a few important things:

• Adds more useful tokens, such as for node fields, to existing modules
• Improves the developer experience for working with tokens
• Provides a user interface for browsing and selecting tokens relevant to the current context

With Token installed, that same dialog is enhanced with a link to a useful token dialog.

This dialog lets you explore all the tokens available, and clicking on a token name inserts it right into your text.

Customization

In addition to the rich built-in features of the token system and Token contributed module, you can extend things in two directions. You might want to allow token replacement on pages you define in your custom modules, or you may want to create new tokens of your own that can be used throughout the site. We'll explore both of these opportunities in future articles.