modules/token/API.txt

$Id: API.txt,v 1.2.2.1 2007/10/29 04:40:41 eaton Exp $

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.
1	$Id: API.txt,v 1.2.2.1 2007/10/29 04:40:41 eaton Exp $
2
3	Overview
4	========
5	In many cases, it's useful to allow users to define patterns or large
6	chunks of text that contain programmatically derived values. For example,
7	form email messages addressed to a given user, or url path aliases
8	containing the title of a given node. Both examples require bits of data
9	that vary each time the text is generated -- node titles, user ids, and
10	so on. Rather than forcing users to embed ugly snippets of PHP, or creating
11	elaborate and bizarre UIs for configuring the patterns via the browser,
12	it's most useful to give users a set of 'placeholder' tokens to place in
13	their text.
14
15	Token.module provides a shared API for exposing and using placeholder
16	tokens and their appropriate replacement values. It does nothing *by
17	itself* -- other modules can use it to avoid reinventing the wheel.
18
19	Using Token Replacement
20	=======================
21	To apply token replacement to a chunk of text, you have two options. The
22	first, and simplest, is:
23
24	token_replace($original, $type = 'global', $object = NULL,
25	$leading = '[', $trailing = ']')
26
27	$original is the source text to perform substitutions on: it can be either
28	a simple string, or an array of multiple strings.
29
30	$type and $object are to be used when performing substitution based on a
31	particular Drupal object. Replacing tokens in an email with values from
32	a particular user account, or replacing tokens in a path alias pattern with
33	values from the node being aliased, are two examples.
34
35	$type should contain the general object type (node, comment, user, etc.)
36	while $object should contain the object itself.
37
38	$leading and $trailing can be used to override the default token style.
39	For example, to replace tokens using %this style, pass in '%' and '' for
40	the $leading and $trailing values. Note that passing in a leading but NOT
41	trailing value can lead to false positives if two tokens are named in a
42	similar fashion (%node_term and %node_term_id, for example).
43
44
45
46	Altering The Replacement Values
47	===============================
48	If your module needs to perform additional cleanup work on the replacement
49	values before doing the actual substitutions (cleaning replacement values
50	to make them appropriate for path aliasing, truncating them to a particular
51	length, etc.) you can manually retrieve the list of tokens and replacement
52	values, then call str_replace() yourself.
53
54	token_get_values($type = 'global', $object = NULL)
55
56	Pass in the $type and $object as you would with the simpler token_replace()
57	function. The return value will be an object containing one array of tokens
58	and one array of values as in this example:
59
60	stdClass Object {
61	[tokens] => array(
62	[0] => mytoken1,
63	[1] => mytoken2
64	),
65	[values] => array(
66	[0] => value1,
67	[1] => value2,
68	)
69	}
70
71
72
73	Providing Placeholder Tokens
74	============================
75	Token.module provides a small set of default placeholders for global values
76	like the name of the currently logged in user, the site's URL, and so on.
77	Any module can provide additional tokens by implementing two hooks.
78
79	Security note: For tokens which include user input, users and modules
80	expect to see both a ['token-name'] and a ['token-name-raw'] value.
81
82
83	hook_token_values($type, $object = NULL)
84	========================================
85	This function should return a keyed array of placeholders, and their
86	replacement values. $type contains the current context -- 'node', 'user',
87	'global', etc. $object contains the specific node, user, etc. that
88	should be used as the basis for the replacements. Only generate and
89	return replacement tokens when $type is something that your module can
90	really deal with. That helps keep things speedy and avoid needlessly
91	searching for jillions of replacement tokens. The $options array can
92	contain additional options (exact use is dynamic and not easily documented).
93
94	For example:
95
96	function my_user_token_values($type, $object = NULL, $options = array()) {
97	if ($type == 'user') {
98	$user = $object;
99	$tokens['name'] = $user->name;
100	$tokens['mail'] = $user->mail;
101	return $tokens;
102	}
103	}
104
105
106	hook_token_list($type = 'all')
107	==============================
108	This function is used to provide help and inline documentation for all
109	of the possible replacement tokens.
110
111	As with hook_token_values, $type indicates the context that token help
112	is being generated for. Unlike hook_token_values however, you should
113	show ALL tokens at the same time if $type is 'all'. As such, the help
114	text should be keyed by the $type context your module will use when
115	doing the actual replacements. For example:
116
117	function my_user_token_list($type = 'all') {
118	if ($type == 'user' \|\| $type == 'all') {
119	$tokens['user']['name'] = t("The user's name");
120	$tokens['user']['mail'] = t("The user's email address");
121	return $tokens;
122	}
123	}
124
125	Examples of more elaborate token replacement setups can be found in the
126	token_node.inc file that's bundled with token.module.
127
128	Security Note
129	========
130	If use any of the tokens in the ['raw'] sub-array then please note that these
131	are unfiltered values which could conceivably contain XSS attacks or other
132	malicious data. Your module should then provide it's own filtering to ensure the
133	safety of site users.