Token hooks are not documented well [#881908]

The documentation could use some extending.

Taking hook_token_info as a victim here:
For example, what's 'needs-data', and what can be used as the key in the 'types' and 'tokens' arrays.

jhodgdon: needs-data tells token what type of data the token needs to have available, sucn as a node, a user, a comment, etc. in order to figure out what the token value is.
jhodgdon: http://api.drupal.org/api/function/hook_tokens/7 sort of implies you can make up your own names
jhodgdon: basically it would be the key in http://api.drupal.org/api/function/token_replace/7 in $data, that the caller of token_replace provides.

So, although it looks like it, the 'needs-data' and other keys are made up (they don't need to match a DB table, entity name, etc. However, in most cases they should, as noted in the core token implementations)

Comment	File	Size	Author
#6	881908-6.patch	5.61 KB	jhodgdon
#3	881908.patch	5.62 KB	jhodgdon

Comments

Comment #1

bojanz commented 13 August 2010 at 01:15

To elaborate, you specify the keys that you want because you're the one who runs token_replace() providing the needed data later on.

So if I do this:

  $code_type = array(
    'name' => t('Affiliate Code'),
    'description' => t('Tokens related to individual codes.'),
    'needs-data' => 'affiliate_code',
  );
  
  $click_type = array(
    'name' => t('Affiliate Click'),
    'description' => t('Tokens related to individual clicks.'),
    'needs-data' => 'affiliate_click',
  );
 
  // defining $code and $click here

  return array(
    'types' => array('affiliate_code' => $code_type, 'affiliate_click' => $click_type),
    'tokens' => array('affiliate_code' => $code, 'affiliate_click' => $click),
  );

Later on when I need the tokens replaced (for example, for sending an email), I do

// I get $code and $click from entity loading functions
$data = array('affiliate_code' => $code, 'affiliate_click' => $click);
$email = token_replace($text, $data);

I hope this helps