Now all modules are in core modules folder
This commit is contained in:
parent
5ba1cdfa0b
commit
05b6a91b0c
1907 changed files with 0 additions and 0 deletions
|
|
@ -1,132 +0,0 @@
|
|||
|
||||
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.
|
||||
Reference in a new issue