[Summary view] [Print] [Text view]

   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.