Tokens

TBA

Table of contents

• Introduction
• Final word

Drupal projects discussed in this chapter: Token, Token Filter.

Introduction

Tokens are specially formatted chunks of text that serve as placeholders for a dynamically generated value. The format looks like this: [key:value].

To take a simple example, if you put [site:name] on your site, it will be replaced by the actual name of your site, provided you arrange for the token to be replaced by its value. You can use a text filter module for this (e.g. Token Filter), or you can do it in code, using the token_replace function.

Some modules make use of tokens. For instance, You can use Token together with Pathauto module to automatically create meaningful URLs for your website.

Tokes are supported by the Drupal 7 core. You don't need to install the Token project to use tokens. The project provides additional tokens not supported by core (most notably fields). It also provides a UI for browsing tokens if you navgate to Help » Token.

The token_replace function

The token_replace function lets you use tokens in your own code.

For the official documentation for the token_replace function, please the Drupal 7 API.

In this chapter, we will give some examples of how to use it.

It looks like this:

function token_replace($text, array $data = array(), array $options = array())

Here is a brief descriptions of the parameters:

$text

A text string potentially containing replaceable tokens.

$data

An optional array of keyed objects. For simple replacement scenarios 'node', 'user', and others are common keys.

$options

A keyed array of settings and flags to control the token replacement process.

The core defines some simple tokens that does not require the second or third argument:

  $text = token_replace('Site name: [site:name].'); dpm($text, 'text');
  $text = token_replace('Site url:  [site:url].'); dpm($text, 'text');
  $text = token_replace('Brief url: [site:url-brief].'); dpm($text, 'text');
  $text = token_replace('Login url: [site:login-url].'); dpm($text, 'text');
  $text = token_replace('Site mail: [site:mail].'); dpm($text, 'text');
  $text = token_replace('Date long: [current-date:long].'); dpm($text, 'text');

Here are some examples using 'node', 'user' as keys:

  $text = token_replace('Node title: [node:title].',
    array('node' => node_load(46))); dpm($text, 'text');
  $text = token_replace('User name: [user:name].',
    array('user' => user_load(2))); dpm($text, 'text');
  $text = token_replace('User mail: [user:mail].',
    array('user' => user_load(2))); dpm($text, 'text');
  $text = token_replace('User edit: [user:edit-url].',
    array('user' => user_load(2))); dpm($text, 'text');

The following shows how to generate a one-time login token for user mails. First, we add a callback function for token_replace() that populate an $replacements array with the return value of user_pass_reset_url() for the user passed in the $data array.

/**
 * Token callback to add a one-time login token for user mails.
 *
 * @param $replacements
 *   An associative array variable containing mappings from token names to
 *   values. Passed by reference.
 * @param $data
 *   An associative array of token replacement values. If the 'user' element
 *   exists, it must contain a user account object with the following
 *   properties:
 *   - login: The UNIX timestamp of the user's last login.
 *   - pass: The hashed account login password.
 * @param $options
 *   Unused parameter required by the token_replace() function.
 */
function hnm_member_mail_tokens(&$replacements, $data, $options) {
  if (isset($data['user'])) {
    $replacements['[user:one-time-login-url]'] = user_pass_reset_url($data['user']);
  }
}

Then, we use this token to get the one-time login url for the user (here #1) into some text that may be inserted into the body of an email:

  $account = user_load(1);
  $data['user'] = $account;
  $body = token_replace('Hi, here is your login url: [user:one-time-login-url].',
    $data, array(
      'callback' => 'hnm_member_mail_tokens',
       'sanitize' => FALSE,
       'clear' => TRUE,
      ),
    );

Final word

---

Last update: 2019-09-18 [gh].