Commit 969135b3 authored by Dries's avatar Dries

- Patch #881908 by jhodgdon: token hooks are not documented well.

parent 2951176d
......@@ -3809,27 +3809,35 @@ function hook_username_alter(&$name, $account) {
/**
* Provide replacement values for placeholder tokens.
*
* This hook is invoked when someone calls token_replace(). That function first
* scans the text for [type:token] patterns, and splits the needed tokens into
* groups by type. Then hook_tokens() is invoked on each token-type group,
* allowing your module to respond by providing replacement text for any of
* the tokens in the group that your module knows how to process.
*
* A module implementing this hook should also implement hook_token_info() in
* order to list its available tokens on editing screens.
*
* @param $type
* The type of token being replaced. 'node', 'user', and 'date' are common.
* The machine-readable name of the type (group) of token being replaced, such
* as 'node', 'user', or another type defined by a hook_token_info()
* implementation.
* @param $tokens
* An array of tokens to be replaced, keyed by the literal text of the token
* as it appeared in the source text.
* An array of tokens to be replaced. The keys are the machine-readable token
* names, and the values are the raw [type:token] strings that appeared in the
* original text.
* @param $data
* (optional) An associative array of objects to be used when generating replacement
* values.
* (optional) An associative array of data objects to be used when generating
* replacement values, as supplied in the $data parameter to token_replace().
* @param $options
* (optional) A associative array of options to control the token
* replacement process. Common options are:
* - 'language' A language object to be used when generating locale-sensitive
* tokens.
* - 'sanitize' A boolean flag indicating that tokens should be sanitized for
* display to a web browser.
* (optional) An associative array of options for token replacement; see
* token_replace() for possible values.
*
* @return
* An associative array of replacement values, keyed by the original 'raw'
* tokens that were found in the source text. For example:
* $results['[node:title]'] = 'My new node';
* An associative array of replacement values, keyed by the raw [type:token]
* strings from the original text.
*
* @see hook_token_info()
* @see hook_tokens_alter()
*/
function hook_tokens($type, $tokens, array $data = array(), array $options = array()) {
......@@ -3929,14 +3937,48 @@ function hook_tokens_alter(array &$replacements, array $context) {
}
/**
* Provide metadata 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.
*
* @return
* An associative array of available tokens and token types, each containing
* the raw name of the token or type, its user-friendly name, and a verbose
* description.
* 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 hook_token_info_alter()
* @see hook_tokens()
*/
function hook_token_info() {
$type = array(
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment