function hook_token_info

You are here

7 system.api.php hook_token_info()
8 system.api.php hook_token_info()

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.

Return value

An associative array of available tokens and token types. The outer array has two components:

  • types: An associative array of token types (groups). Each token type is an associative array with the following components:

    • name: The translated human-readable short name of the token type.
    • description: A translated longer description of the token type.
    • needs-data: The type of data that must be provided to token_replace() in the $data argument (i.e., the key name in $data) in order for tokens of this type to be used in the $text being processed. For instance, if the token needs a node object, 'needs-data' should be 'node', and to use this token in token_replace(), the caller needs to supply a node object as $data['node']. Some token data can also be supplied indirectly; for instance, a node object in $data supplies a user object (the author of the node), allowing user tokens to be used when only a node data object is supplied.
  • tokens: An associative array of tokens. The outer array is keyed by the group name (the same key as in the types array). Within each group of tokens, each token item is keyed by the machine name of the token, and each token item has the following components:

    • name: The translated human-readable short name of the token.
    • description: A translated longer description of the token.
    • type (optional): A 'needs-data' data type supplied by this token, which should match a 'needs-data' value from another token type. For example, the node author token provides a user object, which can then be used for token replacement data in token_replace() without having to supply a separate user object.

See also

hook_token_info_alter()

hook_tokens()

Related topics

7 functions implement hook_token_info()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

comment_token_info in modules/comment/comment.tokens.inc
Implements hook_token_info().
node_token_info in modules/node/node.tokens.inc
Implements hook_token_info().
poll_token_info in modules/poll/poll.tokens.inc
Implements hook_token_info().
statistics_token_info in modules/statistics/statistics.tokens.inc
Implements hook_token_info().
system_token_info in modules/system/system.tokens.inc
Implements hook_token_info().

... See full list

1 invocation of hook_token_info()
token_info in includes/token.inc
Returns metadata describing supported tokens.

File

modules/system/system.api.php, line 4460
Hooks provided by Drupal core and the System module.

Code

function hook_token_info() {
  $type = array(
    'name' => t('Nodes'),
    'description' => t('Tokens related to individual nodes.'),
    'needs-data' => 'node',
  );

  // Core tokens for nodes.
  $node['nid'] = array(
    'name' => t("Node ID"),
    'description' => t("The unique ID of the node."),
  );
  $node['title'] = array(
    'name' => t("Title"),
    'description' => t("The title of the node."),
  );
  $node['edit-url'] = array(
    'name' => t("Edit URL"),
    'description' => t("The URL of the node's edit page."),
  );

  // Chained tokens for nodes.
  $node['created'] = array(
    'name' => t("Date created"),
    'description' => t("The date the node was posted."),
    'type' => 'date',
  );
  $node['author'] = array(
    'name' => t("Author"),
    'description' => t("The author of the node."),
    'type' => 'user',
  );

  return array(
    'types' => array('node' => $type),
    'tokens' => array('node' => $node),
  );
}

Comments

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

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;
}

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'.

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

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

<?php
// 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
?>