132 lines
5.1 KiB
Text
132 lines
5.1 KiB
Text
|
|
Overview
|
|
========
|
|
In many cases, it's useful to allow users to define patterns or large
|
|
chunks of text that contain programmatically derived values. For example,
|
|
form email messages addressed to a given user, or url path aliases
|
|
containing the title of a given node. Both examples require bits of data
|
|
that vary each time the text is generated -- node titles, user ids, and
|
|
so on. Rather than forcing users to embed ugly snippets of PHP, or creating
|
|
elaborate and bizarre UIs for configuring the patterns via the browser,
|
|
it's most useful to give users a set of 'placeholder' tokens to place in
|
|
their text.
|
|
|
|
Token.module provides a shared API for exposing and using placeholder
|
|
tokens and their appropriate replacement values. It does nothing *by
|
|
itself* -- other modules can use it to avoid reinventing the wheel.
|
|
|
|
Using Token Replacement
|
|
=======================
|
|
To apply token replacement to a chunk of text, you have two options. The
|
|
first, and simplest, is:
|
|
|
|
token_replace($original, $type = 'global', $object = NULL,
|
|
$leading = '[', $trailing = ']')
|
|
|
|
$original is the source text to perform substitutions on: it can be either
|
|
a simple string, or an array of multiple strings.
|
|
|
|
$type and $object are to be used when performing substitution based on a
|
|
particular Drupal object. Replacing tokens in an email with values from
|
|
a particular user account, or replacing tokens in a path alias pattern with
|
|
values from the node being aliased, are two examples.
|
|
|
|
$type should contain the general object type (node, comment, user, etc.)
|
|
while $object should contain the object itself.
|
|
|
|
$leading and $trailing can be used to override the default token style.
|
|
For example, to replace tokens using %this style, pass in '%' and '' for
|
|
the $leading and $trailing values. Note that passing in a leading but NOT
|
|
trailing value can lead to false positives if two tokens are named in a
|
|
similar fashion (%node_term and %node_term_id, for example).
|
|
|
|
|
|
|
|
Altering The Replacement Values
|
|
===============================
|
|
If your module needs to perform additional cleanup work on the replacement
|
|
values before doing the actual substitutions (cleaning replacement values
|
|
to make them appropriate for path aliasing, truncating them to a particular
|
|
length, etc.) you can manually retrieve the list of tokens and replacement
|
|
values, then call str_replace() yourself.
|
|
|
|
token_get_values($type = 'global', $object = NULL)
|
|
|
|
Pass in the $type and $object as you would with the simpler token_replace()
|
|
function. The return value will be an object containing one array of tokens
|
|
and one array of values as in this example:
|
|
|
|
stdClass Object {
|
|
[tokens] => array(
|
|
[0] => mytoken1,
|
|
[1] => mytoken2
|
|
),
|
|
[values] => array(
|
|
[0] => value1,
|
|
[1] => value2,
|
|
)
|
|
}
|
|
|
|
|
|
|
|
Providing Placeholder Tokens
|
|
============================
|
|
Token.module provides a small set of default placeholders for global values
|
|
like the name of the currently logged in user, the site's URL, and so on.
|
|
Any module can provide additional tokens by implementing two hooks.
|
|
|
|
Security note: For tokens which include user input, users and modules
|
|
expect to see both a ['token-name'] and a ['token-name-raw'] value.
|
|
|
|
|
|
hook_token_values($type, $object = NULL)
|
|
========================================
|
|
This function should return a keyed array of placeholders, and their
|
|
replacement values. $type contains the current context -- 'node', 'user',
|
|
'global', etc. $object contains the specific node, user, etc. that
|
|
should be used as the basis for the replacements. *Only* generate and
|
|
return replacement tokens when $type is something that your module can
|
|
really deal with. That helps keep things speedy and avoid needlessly
|
|
searching for jillions of replacement tokens. The $options array can
|
|
contain additional options (exact use is dynamic and not easily documented).
|
|
|
|
For example:
|
|
|
|
function my_user_token_values($type, $object = NULL, $options = array()) {
|
|
if ($type == 'user') {
|
|
$user = $object;
|
|
$tokens['name'] = $user->name;
|
|
$tokens['mail'] = $user->mail;
|
|
return $tokens;
|
|
}
|
|
}
|
|
|
|
|
|
hook_token_list($type = 'all')
|
|
==============================
|
|
This function is used to provide help and inline documentation for all
|
|
of the possible replacement tokens.
|
|
|
|
As with hook_token_values, $type indicates the context that token help
|
|
is being generated for. Unlike hook_token_values however, you should
|
|
show ALL tokens at the same time if $type is 'all'. As such, the help
|
|
text should be keyed by the $type context your module will use when
|
|
doing the actual replacements. For example:
|
|
|
|
function my_user_token_list($type = 'all') {
|
|
if ($type == 'user' || $type == 'all') {
|
|
$tokens['user']['name'] = t("The user's name");
|
|
$tokens['user']['mail'] = t("The user's email address");
|
|
return $tokens;
|
|
}
|
|
}
|
|
|
|
Examples of more elaborate token replacement setups can be found in the
|
|
token_node.inc file that's bundled with token.module.
|
|
|
|
Security Note
|
|
========
|
|
If use any of the tokens in the ['raw'] sub-array then please note that these
|
|
are unfiltered values which could conceivably contain XSS attacks or other
|
|
malicious data. Your module should then provide it's own filtering to ensure the
|
|
safety of site users.
|