[Summary view] [Print] [Text view]

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