Internal Projects

$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.