Backdrop placeholder/token replacement system.

API functions for replacing placeholders in text with meaningful values.

For example: When configuring automated emails, an administrator enters standard text for the email. Variables like the title of a node and the date the email was sent can be entered as placeholders like [node:title] and [date:short]. When a Backdrop module prepares to send the email, it can call the token_replace() function, passing in the text. The token system will scan the text for placeholder tokens, give other modules an opportunity to replace them with meaningful text, then return the final product to the original module.

Tokens follow the form: [$type:$name], where $type is a general class of tokens like 'node', 'user', or 'comment' and $name is the name of a given placeholder. For example, [node:title] or [node:created:since].

In addition to raw text containing placeholders, modules may pass in an array of objects to be used when performing the replacement. The objects should be keyed by the token type they correspond to. For example:

// Load a node and a user, then replace tokens in the text.
$text = 'On [date:short], [user:name] read [node:title].';
$node = node_load(1);
$user = user_load(1);

// [date:...] tokens use the current date automatically.
$data = array('node' => $node, 'user' => $user);
return token_replace($text, $data);

Some tokens may be chained in the form of [$type:$pointer:$name], where $type is a normal token type, $pointer is a reference to another token type, and $name is the name of a given placeholder. For example, [node:author:mail]. In that example, 'author' is a pointer to the 'user' account that created the node, and 'mail' is a placeholder available for any 'user'.

See also

token_replace()

hook_tokens()

hook_token_info()

File

core/includes/token.inc

Functions

Namesort descending Description
token_build_tree Build a tree array of tokens used for theming or information.
token_cache_clear Clear token caches and static variables.
token_clean_token_name Prepare a string for use as a valid token name.
token_element_validate Validate a form element that should have tokens in it.
token_find_with_prefix Returns a list of tokens that begin with a specific prefix.
token_flatten_tree Flatten a token tree.
token_generate Generates replacement values for a list of tokens.
token_get_global_token_types Get a list of token types that can be used without any context (global).
token_get_info Retrieve, sort, store token info from the cache.
token_get_invalid_tokens Validate an array of tokens based on their token type.
token_get_invalid_tokens_by_context Validate an tokens in raw text based on possible contexts.
token_get_module Return the module responsible for a token.
token_get_token_problems Retrieves the current list of all site tokens and checks for common problems.
token_info Returns metadata describing supported tokens.
token_render_array Renders a render array for display as a token.
token_render_array_value Renders a render array for display as a token.
token_replace Replaces all tokens in a given string with appropriate values.
token_scan Builds a list of all token-like patterns that appear in the text.
token_type_load Loads a token type.
_token_build_tree Recursive helper for token_build_tree().