← Back to branch summary

~spreadubuntu/spreadubuntu/devel-drupal6

« back to all changes in this revision

Viewing changes to modules/token/token.module

  • Committer: ruben
  • Date: 2009-06-08 09:38:49 UTC
  • Revision ID: ruben@captive-20090608093849-s1qtsyctv2vwp1x1
SpreadUbuntu moving to Drupal6. Based on ubuntu-drupal theme and adding our modules

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/token/token.module
 
1
<?php
 
2
// $Id: token.module,v 1.7.4.8 2008/07/14 19:15:10 greggles Exp $
 
3
 
 
4
/**
 
5
 * @file
 
6
 * The Token API module.
 
7
 *
 
8
 * The Token module provides an API for providing tokens to other modules.
 
9
 * Tokens are small bits of text that can be placed into larger documents
 
10
 * via simple placeholders, like %site-name or [user].
 
11
 *
 
12
 * @ingroup token
 
13
 */
 
14
 
 
15
function token_theme() {
 
16
  return array(
 
17
    'token_help' => array(
 
18
      'arguments' => array('type' => 'all', 'prefix' => '[', 'suffix' => ']')
 
19
    ),
 
20
  );
 
21
}
 
22
 
 
23
/**
 
24
 * For a given context, builds a formatted list of tokens and descriptions
 
25
 * of their replacement values.
 
26
 *
 
27
 * @param type
 
28
 *    The token types to display documentation for. Defaults to 'all'.
 
29
 * @param prefix
 
30
 *    The prefix your module will use when parsing tokens. Defaults to '['
 
31
 * @param suffix
 
32
 *    The suffix your module will use when parsing tokens. Defaults to ']'
 
33
 * @return An HTML table containing the formatting docs.
 
34
 */
 
35
function theme_token_help($type = 'all', $prefix = '[', $suffix = ']') {
 
36
  token_include();
 
37
  $full_list = token_get_list($type);
 
38
 
 
39
  $headers = array(t('Token'), t('Replacement value'));
 
40
  $rows = array();
 
41
  foreach ($full_list as $key => $category) {
 
42
    $rows[] = array(array('data' => drupal_ucfirst($key) .' '. t('tokens'), 'class' => 'region', 'colspan' => 2));
 
43
    foreach ($category as $token => $description) {
 
44
      $row = array();
 
45
      $row[] = $prefix . $token . $suffix;
 
46
      $row[] = $description;
 
47
      $rows[] = $row;
 
48
    }
 
49
  }
 
50
 
 
51
  $output = theme('table', $headers, $rows, array('class' => 'description'));
 
52
  return $output;
 
53
}
 
54
 
 
55
/**
 
56
 * Sample implementation of hook_token_values().
 
57
 *
 
58
 * @param type
 
59
 *   A flag indicating the class of substitution tokens to use. If an
 
60
 *   object is passed in the second param, 'type' should contain the
 
61
 *   object's type. For example, 'node', 'comment', or 'user'. If your
 
62
 *   implemention of the hook inserts globally applicable tokens that
 
63
 *   do not depend on a particular object, it should only return values
 
64
 *   when $type is 'global'.
 
65
 * @param object
 
66
 *   Optionally, the object to use for building substitution values.
 
67
 *   A node, comment, user, etc.
 
68
 * @return
 
69
 *   A keyed array containing the substitution tokens and the substition
 
70
 *   values for the passed-in type and object.
 
71
 */
 
72
function token_token_values($type, $object = NULL) {
 
73
  global $user;
 
74
  global $base_url;
 
75
  $values = array();
 
76
 
 
77
  switch ($type) {
 
78
    case 'global':
 
79
      $values['user-name']    = $user->uid ? $user->name : variable_get('anonymous', t('Anonymous'));
 
80
      $values['user-id']      = $user->uid ? $user->uid : 0;
 
81
      $values['user-mail']    = $user->uid ? $user->mail : '';
 
82
      $values['site-url']     = $base_url;
 
83
      $values['site-name']    = variable_get('site_name', t('Drupal'));
 
84
      $values['site-slogan']  = variable_get('site_slogan', '');
 
85
      $values['site-mission'] = filter_xss_admin(variable_get('site_mission', ''));
 
86
      $values['site-mail']    = variable_get('site_mail', '');
 
87
      $values['site-date']    = format_date(time(), 'short', '', variable_get('date_default_timezone', 0));
 
88
      break;
 
89
  }
 
90
  return $values;
 
91
}
 
92
 
 
93
/**
 
94
 * Sample implementation of hook_token_list(). Documents the individual
 
95
 * tokens handled by your module.
 
96
 *
 
97
 * @param type
 
98
 *   A flag indicating the class of substitution tokens to return
 
99
 *   information on. If this is set to 'all', a complete list is being
 
100
 *   built and your module should return its full list, regardless of
 
101
 *   type. Global tokens should always be returned, regardless of the
 
102
 *   $type passed in.
 
103
 * @return
 
104
 *   A keyed array listing the substitution tokens. Elements should be
 
105
 *   in the form of: $list[$type][$token] = $description
 
106
 */
 
107
function token_token_list($type = 'all') {
 
108
  $tokens['global']['user-name']    = t('The name of the currently logged in user.');
 
109
  $tokens['global']['user-id']      = t('The user ID of the currently logged in user.');
 
110
  $tokens['global']['user-mail']    = t('The email address of the currently logged in user.');
 
111
  $tokens['global']['site-url']     = t('The url of the current Drupal website.');
 
112
  $tokens['global']['site-name']    = t('The name of the current Drupal website.');
 
113
  $tokens['global']['site-slogan']  = t('The slogan of the current Drupal website.');
 
114
  $tokens['global']['site-mission'] = t('The mission of the current Drupal website.');
 
115
  $tokens['global']['site-mail']    = t('The contact email address for the current Drupal website.');
 
116
  $tokens['global']['site-date']    = t("The current date on the site's server.");
 
117
  return $tokens;
 
118
}
 
119
 
 
120
/**
 
121
 * General function to include the files that token relies on for the real work.
 
122
 *
 
123
 */
 
124
function token_include() {
 
125
  $path = drupal_get_path('module', 'token');
 
126
  require_once("$path/token_node.inc");
 
127
  require_once("$path/token_user.inc");
 
128
  if (module_exists('taxonomy')) {
 
129
    require_once("$path/token_taxonomy.inc");
 
130
  }
 
131
  if (module_exists('comment')) {
 
132
    require_once("$path/token_comment.inc");
 
133
  }
 
134
 
 
135
}
 
136
 
 
137
/**
 
138
 * Return the value of $original, with all instances of placeholder
 
139
 * tokens replaced by their proper values. To replace mutliple types
 
140
 * at once see token_replace_multiple().
 
141
 *
 
142
 * @param original
 
143
 *  A string, or an array of strings, to perform token substitutions
 
144
 *  on.
 
145
 * @param type
 
146
 *   A flag indicating the class of substitution tokens to use. If an
 
147
 *   object is passed in the second param, 'type' should contain the
 
148
 *   object's type. For example, 'node', 'comment', or 'user'. If no
 
149
 *   type is specified, only 'global' site-wide substitution tokens are
 
150
 *   built.
 
151
 * @param object
 
152
 *   Optionally, the object to use for building substitution values.
 
153
 *   A node, comment, user, etc.
 
154
 * @param leading
 
155
 *    Character(s) to prepend to the token key before searching for
 
156
 *    matches. Defaults to an open-bracket.
 
157
 * @param trailing
 
158
 *    Character(s) to append to the token key before searching for
 
159
 *    matches. Defaults to a close-bracket.
 
160
 * @return The modified version of $original, with all substitutions
 
161
 *   made.
 
162
 */
 
163
function token_replace($original, $type = 'global', $object = NULL, $leading = '[', $trailing = ']', $options = array()) {
 
164
  $full = token_get_values($type, $object, FALSE, $options);
 
165
  return _token_replace_tokens($original, $full->tokens, $full->values, $leading, $trailing);
 
166
}
 
167
 
 
168
/**
 
169
 * Return the value of $original, with all instances of placeholder
 
170
 * tokens replaced by their proper values. Contrary to token_replace(),
 
171
 * this function supports replacing mutiple types.
 
172
 *
 
173
 * @param original
 
174
 *  A string, or an array of strings, to perform token substitutions
 
175
 *  on.
 
176
 * @param types
 
177
 *   An array of substitution classes and optional objects. The key is
 
178
 *   a flag indicating the class of substitution tokens to use.
 
179
 *   If an object is passed as value, the key should contain the
 
180
 *   object's type. For example, 'node', 'comment', or 'user'. The
 
181
 *   object will be used for building substitution values. If no type
 
182
 *   is specified, only 'global' site-wide substitution tokens are built.
 
183
 * @param leading
 
184
 *    Character(s) to prepend to the token key before searching for
 
185
 *    matches. Defaults to an open-bracket.
 
186
 * @param trailing
 
187
 *    Character(s) to append to the token key before searching for
 
188
 *    matches. Defaults to a close-bracket.
 
189
 * @return The modified version of $original, with all substitutions
 
190
 *   made.
 
191
 */
 
192
function token_replace_multiple($original, $types = array('global' => NULL), $leading = '[', $trailing = ']', $options = array()) {
 
193
  $full = new stdClass();
 
194
  $full->tokens = $full->values = array();
 
195
  foreach ($types as $type => $object) {
 
196
    $temp = token_get_values($type, $object, FALSE, $options);
 
197
    $full->tokens = array_merge($full->tokens, $temp->tokens);
 
198
    $full->values = array_merge($full->values, $temp->values);
 
199
  }
 
200
  return _token_replace_tokens($original, $full->tokens, $full->values, $leading, $trailing);
 
201
}
 
202
 
 
203
// Internally used function to replace tokens.
 
204
function _token_replace_tokens($original, $tokens, $values, $leading, $trailing) {
 
205
  $tokens = token_prepare_tokens($tokens, $leading, $trailing);
 
206
  return str_replace($tokens, $values, $original);
 
207
}
 
208
 
 
209
/**
 
210
 * Return a list of valid substitution tokens and their values for
 
211
 * the specified type.
 
212
 *
 
213
 * @param type
 
214
 *   A flag indicating the class of substitution tokens to use. If an
 
215
 *   object is passed in the second param, 'type' should contain the
 
216
 *   object's type. For example, 'node', 'comment', or 'user'. If no
 
217
 *   type is specified, only 'global' site-wide substitution tokens are
 
218
 *   built.
 
219
 * @param object
 
220
 *   Optionally, the object to use for building substitution values.
 
221
 *   A node, comment, user, etc.
 
222
 * @return
 
223
 *   A keyed array containing the substitution tokens and the substition
 
224
 *   values for the passed-in type and object.
 
225
 */
 
226
function token_get_values($type = 'global', $object = NULL, $flush = FALSE, $options = array()) {
 
227
  static $tokens;
 
228
  static $running;
 
229
 
 
230
  // Flush the static token cache. Useful for processes that need to slog through
 
231
  // huge numbers of tokens in a single execution cycle. Flushing it will keep
 
232
  // them from burning through memory.
 
233
  if ($flush || !isset($tokens)) {
 
234
    $tokens = array();
 
235
  }
 
236
 
 
237
  // Since objects in PHP5 are always passed by reference, we ensure we're
 
238
  // working on a copy of the object.
 
239
  if (is_object($object)) {
 
240
    $object = drupal_clone($object);
 
241
  }
 
242
 
 
243
  // Simple recursion check. This is to avoid content_view()'s potential
 
244
  // for endless looping when a filter uses tokens, which load the content
 
245
  // view, which calls the filter, which uses tokens, which...
 
246
  if ($running) {
 
247
    // We'll allow things to get two levels deep, but bail out after that
 
248
    // without performing any substitutions.
 
249
    $result = new stdClass();
 
250
    $result->tokens = array();
 
251
    $result->values = array();
 
252
    return $result;
 
253
  }
 
254
 
 
255
  $running = TRUE;
 
256
 
 
257
  token_include();
 
258
 
 
259
  $id = _token_get_id($type, $object);
 
260
  if (isset($tokens[$type][$id])) {
 
261
    $tmp_tokens = $tokens[$type][$id];
 
262
  }
 
263
  else {
 
264
    $tmp_tokens = module_invoke_all('token_values', $type, $object, $options);
 
265
    $tokens[$type][$id] = $tmp_tokens;
 
266
  }
 
267
 
 
268
  // Special-case global tokens, as we always want to be able to process
 
269
  // those substitutions.
 
270
  if (!isset($tokens['global']['default'])) {
 
271
    $tokens['global']['default'] = module_invoke_all('token_values', 'global');
 
272
  }
 
273
 
 
274
  $all = array_merge($tokens['global']['default'], $tokens[$type][$id]);
 
275
 
 
276
  $result = new stdClass();
 
277
  $result->tokens = array_keys($all);
 
278
  $result->values = array_values($all);
 
279
 
 
280
  $running = FALSE;
 
281
 
 
282
  return $result;
 
283
}
 
284
 
 
285
/**
 
286
 * A helper function that retrieves all currently exposed tokens,
 
287
 * and merges them recursively. This is only necessary when building
 
288
 * the token listing -- during actual value replacement, only tokens
 
289
 * in a particular domain are requested and a normal array_marge() is
 
290
 * sufficient.
 
291
 *
 
292
 * @param type
 
293
 *   A flag indicating the class of substitution tokens to use. If an
 
294
 *   object is passed in the second param, 'type' should contain the
 
295
 *   object's type. For example, 'node', 'comment', or 'user'. If no
 
296
 *   type is specified, only 'global' site-wide substitution tokens are
 
297
 *   built.
 
298
 * @return
 
299
 *   The array of usable tokens and their descriptions, organized by
 
300
 *   token type.
 
301
 */
 
302
function token_get_list($type = 'all') {
 
303
  token_include();
 
304
  $return = array();
 
305
  foreach (module_implements('token_list') as $module) {
 
306
    $function = $module .'_token_list';
 
307
    $result = $function($type);
 
308
    if (is_array($result)) {
 
309
      foreach ($result as $category => $tokens) {
 
310
        foreach ($tokens as $token => $title) {
 
311
          $return[$category][$token] = $title;
 
312
        }
 
313
      }
 
314
    }
 
315
  }
 
316
  return $return;
 
317
}
 
318
 
 
319
/**
 
320
 * A helper function that transforms all the elements of an
 
321
 * array. Used to change the delimiter style from brackets to
 
322
 * percent symbols etc.
 
323
 *
 
324
 * @param tokens
 
325
 *    The array of tokens keys with no delimiting chacaters
 
326
 * @param leading
 
327
 *    Character(s) to prepend to the token key before searching for
 
328
 *    matches. Defaults to an open-bracket.
 
329
 * @param trailing
 
330
 *    Character(s) to append to the token key before searching for
 
331
 *    matches. Defaults to a close-bracket.
 
332
 *  @return
 
333
 *    The array of token keys, each wrapped in the specified
 
334
 *    delimiter style.
 
335
 */
 
336
function token_prepare_tokens($tokens = array(), $leading = '[', $trailing = ']') {
 
337
  foreach ($tokens as $key => $value) {
 
338
    $tokens[$key] = $leading . $value . $trailing;
 
339
  }
 
340
  return $tokens;
 
341
}
 
342
 
 
343
// Internal utility function used for static caching. There are
 
344
// almost certainly better ways to do this, but for the moment it's
 
345
// sufficient.
 
346
function _token_get_id($type = 'global', $object = NULL) {
 
347
  if (!isset($object)) {
 
348
    return "default";
 
349
  }
 
350
  switch ($type) {
 
351
    case 'node':
 
352
      return $object->nid;
 
353
    case 'comment':
 
354
      return $object->cid;
 
355
    case 'user':
 
356
      return $object->uid;
 
357
    default:
 
358
      return crc32(serialize($object));
 
359
  }
 
360
}