Module Development

Providing Values For Placeholder Tokens for Drupal 7

This page is archived

We're keeping this page up as a courtesy to folks who may need to refer to old instructions. We don't plan to update this page.

Sprout Video

Note: In the video, around 9:30, we added at the :uid argument to the query, but did not add the corresponding portion to the WHERE clause of the query. The final query should look like the one in the code sample below.

Now that we've got placeholder tokens that we can enter into a string of text we need to provide the actual values that should be used to replace those placeholders. In this lesson we'll implement hook_tokens() in order to provide the Drupal Token API with the values that correspond to the placeholders our module provides.

Implementations of hook_tokens() are called once for every token type that's in scope for the current string that's being processed. So, one for all user tokens, once for all node tokens, and once for all global tokens. Each time the hook is passed an array which contains all the tokens of that specific type that where found in the string being processed as well as any additional contextual information such as the current $user or $node object.

hook_tokens() is expected to return an array of values for each of the tokens in question that your module is responsible for. In our case, since we added the [databasics-page:*] and [databasics-totals:*] tokens we're responsible for calculating and returning their value whenever they are requested.

We'll also look at using the token_find_with_prefix() function which will allow us to detect and provide values for any chained tokens. Like for example [node:view-count:last-viewed].


 * Implements hook_tokens().
function databasics_tokens($type, $tokens, array $data = array(), array $options = array()) {
  $replacements = array();
  if ($type == 'databasics-totals') {
    foreach($tokens as $name => $original) {
      switch($name) {
        case 'count':
          $count = db_query('SELECT SUM(view_count) FROM {databasics}')->fetchField();
          $replacements[$original] = $count;
  if ($type == 'databasics-page' && !empty($data['databasics_record'])) {
    $record = $data['databasics_record'];
    foreach ($tokens as $name => $original) {
      switch ($name) {
        case 'view-count':
          $replacements[$original] = $record->view_count;
        case 'last-viewed':
          $replacements[$original] = $record->last_viewed;
  if ($type == 'node' && isset($tokens['view-count']) && !empty($data['node'])) {
    $node = $data['node'];
    global $user;
    $count = db_query('SELECT SUM(view_count) FROM {databasics} WHERE nid = :nid AND uid = :uid', array(':nid' => $node->nid, ':uid' => $user->uid))->fetchField();
    $replacements[$tokens['view-count']] = $count;
    // [node:view-count:last-viewed]
    if ($count_tokens = token_find_with_prefix($tokens, 'view-count')) {
      $record = databasics_get_record($node->nid, $user->uid);
      $replacements += token_generate('databasics-page', $count_tokens, array('databasics_record' => $record), $options);
  return $replacements;

Additional resources