\hook_token_info
function
Provide information about available placeholder tokens and token types.

Provide information about available placeholder tokens and token types.

Tokens are placeholders that can be put into text by using the syntax [type:token], where type is the machine-readable name of a token type, and token is the machine-readable name of a token within this group. This hook provides a list of types and tokens to be displayed on text editing screens, so that people editing text can see what their token options are.

The actual token replacement is done by token_replace(), which invokes hook_tokens(). Your module will need to implement that hook in order to generate token replacements from the tokens defined here.

Comments

manimejia’s picture

Invoked by function token_info(). See file token.inc for more info.

Aeternum’s picture

Just an example on how to use this function to define a new token type:

function yourmodulename_token_info()
{
  $info['tokens']['user']['machine_name_of_your_token'] = array(
    'name' => t('Your token name'),
    'description' => t('The description of your token name'),
  );

  return $info;
}
woop_light’s picture

Thanks. How would I add it to the node type rather than making it custom?

EDIT: here's the answer.

function MYMODULENAME_token_info() {
  $info['tokens']['node']['first_letter'] = array(
    'name' => t('First Letter'),
    'description' => t("The first letter of the node title."),
  );
  return $info;
}

this will make it show up in your list of tokens under 'nodes'.

pferlito’s picture

This is a new token on the user type, not a new token type.

pcambra’s picture

marcoscano’s picture

Even if it's not mentioned here, when you are defining a generic token, you may ommit the "needs-data" component.

zorroposada’s picture

I wanted to display or present my custom group of tokens as a nested list in the Token browser.
I created a custom module and implemented hook_token_info and hook_tokens
I was able to see my custom group of tokens but I wanted to add groups inside my group like:

Custom Group
- Token 1 -> [custom_group:token1]
- Token 2 -> [custom_group:token2]
- Sub Group 1 -> [custom_group:sub_group1]
-- Token 3 -> [custom_group:sub_group1:token3]
-- Token 4 -> [custom_group:sub_group1:token4]

This is possible if you set "needs-data" to point to my "custom_group" as follows

// inside hook_token_info

$info['types']['custom_group'] = array( // define main group
  'name' => t('Custom Group'),
  'description' => t('Custom Group'), 
);
$info['tokens']['custom_group']['token1'] = array( // first level token
  'name' => t('Token 1'),
  'description' => t('Token 1'), 
);
// ... more tokens

$info['types']['sub_group1'] = array( // define first nested group
  'name' => t('Sub Group 1'),
  'description' => t('Sub Group 1'),
  'needs-data' => 'custom_group', // tells drupal to nest this type inside custom_group
);
$info['tokens']['custom_group']['sub_group1'] = array( // define sub group as first level token
  'name' => t('Sub Group 1'),
  'description' => t('Sub Group 1'), 
  'type' => 'sub_group1', // tells drupal that this token belongs to sub_group1
);
$info['tokens']['sub_group1']['token3'] = array( // second level token
  'name' => t('Token 3'),
  'description' => t('Token 3'), 
);
// ... more tokens

fcastand’s picture

I test the following code but it doesn't appear in the list of tokens availables in token/help. It is Normal?
function yourmodulename_token_info()
{
$info['tokens']['user']['machine_name_of_your_token'] = array(
'name' => t('Your token name'),
'description' => t('The description of your token name'),
);

return $info;

Thanks.
}

hyperlinked’s picture

I'm not sure what you're looking at in Token help. My token help has a useless README page and that's all.

I had some problems with this myself. If you're having the same issue, I'll describe my epiphany to you. I wanted to add an extra token to the user welcome email. I have a custom module and after implenting hook_token_info(), I saw the name of the token appear when I browsed the list of available tokens when editing the welcome email, but I didn't add the token to the email at that time.

I then went to my hook_tokens() instance and did a dpm on the $tokens array expecting to see the machine name of my token value as a key in the $tokens array. What I didn't realize is that the $tokens array reflects the tokens that are being called by the content where the tokens are to be applied. Once I added [current-user:my-token-name] to the welcome email, the expected token key appeared.

I went around in circles trying everything thinking that I did it wrong or made an invisible typo. I hope this saves someone the same frustration.

Anu Anusha’s picture

Make sure that you enable your custom token globally available(admin/config/content/token_insert) in the interface after flushing the cache.

cravecode’s picture

To render a token with a "?" at the end, indicating that it accepts arguments, specify '"dynamic" => true' when defining your token.

drugget’s picture

Easy example how to create a custom node token
(found here: http://web-tricks.org/content/drupal-7-how-create-custom-node-token):

function MYMODULE_token_info() {
  $info['tokens']['node']['title_first_letter'] = array(
    'name' => t('Title first letter'),
    'description' => t('Generates first letter of node title')
  );
  return $info;
}

function slideaway_currency_tokens($type, $tokens, array $data = array(), array $options = array()) {
  $replacements = array();
  if ($type == 'node' && !empty($data['node'])) {
    $node = $data['node'];
    foreach ($tokens as $name => $original) {
      switch ($name) {
        case 'title_first_letter':
          $replacements[$original] = substr($node->title, 0, 1); // get first letter of the title here 
          break;
      }
    }
  }
  return $replacements;
}