Merge pull request #677 from mattwire/token_examples

Add token/tokenValues hook examples

docs/hooks/hook_civicrm_tokenValues.md

@@ -14,17 +14,76 @@ usage examples.
 
 ## Definition
 
-    hook_civicrm_tokenValues(&$values, $cids, $job = null, $tokens = array(), $context = null)
+```php
+hook_civicrm_tokenValues(&$values, $cids, $job = null, $tokens = [], $context = null)
+```
 
 ## Parameters
 
--   $values - array of values, keyed by contact id
--   $cids - array of contactIDs that the system needs values for.
--   $job - the job_id
--   $tokens - tokens used in the mailing - use this to check whether a
-    token is being used and avoid fetching data for unneeded tokens
--   $context - the class name
+- $values - array of values, keyed by contact id
+- $cids - array of contactIDs that the system needs values for.
+- $job - the job_id
+- $tokens - tokens used in the mailing - use this to check whether a
+  token is being used and avoid fetching data for unneeded tokens
+- $context - the class name
 
 ## Returns
 
--   null
\ No newline at end of file
+- null
+
+## Example
+
+```php
+function customtokens_civicrm_tokenValues(&$values, $cids, $job = null, $tokens = [], $context = null) {
+  $group = 'team';
+  if(isset($tokens[$group])) {
+    $token = 'team_number';
+    if (!customtokens_isTokenRequested($tokens, $group, $token)) {
+      return;
+    }
+
+    foreach ($cids as $cid) {
+      // get team (employer) id
+          $individualResult = civicrm_api3('Contact', 'getsingle', [
+        'return' => ["current_employer_id"],
+        'contact_id' => $cid,
+      ]);
+
+      // if there is a team (employer) id, get team number for the team (employer)
+      if(!$individualResult['is_error'] && isset($individualResult['current_employer_id']) && strlen($individualResult['current_employer_id'])){
+
+        $teamResult = civicrm_api3('Contact', 'getsingle', [
+          'return' => ["custom_70"],
+          'id' => $individualResult['current_employer_id'],
+        ]);
+
+        // if there is a team number, display it as the token
+        if(!$teamResult['is_error'] && isset($teamResult['custom_70'])) {
+          $values[$cid]['team.team_number'] = $teamResult['custom_70'];
+        }
+      }
+    }
+  }
+}
+
+/**
+ * "Send an Email" and "CiviMail" send different parameters to the tokenValues hook (in CiviCRM 5.x).
+ * This works around that.
+ *
+ * @param array $tokens
+ * @param string $group
+ * @param string $token
+ *
+ * @return bool
+ */
+function customtokens_isTokenRequested($tokens, $group, $token) {
+  // CiviMail sets $tokens to the format:
+  //   [ 'group' => [ 'token_name' => 1 ] ]
+  // "Send an email" sets $tokens to the format:
+  //  [ 'group' => [ 0 => 'token_name' ] ]
+  if (array_key_exists($token, $tokens[$group]) || in_array($token, $tokens[$group])) {
+    return TRUE;
+  }
+  return FALSE;
+}
+```

docs/hooks/hook_civicrm_tokens.md

@@ -15,25 +15,38 @@ for usage examples.
 
 ## Definition
 
-    hook_civicrm_tokens( &$tokens )
+```php
+hook_civicrm_tokens(&$tokens)
+```
 
 ## Parameters
 
--   $tokens: reference to the associative array of custom tokens that
-    are available to be used in mailings and other contexts. This will
-    be an empty array unless an implementation of hook_civicrm_tokens
-    adds items to it. Items should be added in this format:
-     
-
-        $tokens['date'] = array(
-            'date.date_short' => ts("Today's Date: short format"),
-            'date.date_med' => ts("Today's Date: med format"),
-            'date.date_long' => ts("Today's Date: long format"),
-        );
-        $tokens['party'] = array(
-            'party.balloons' => ts("Number of balloons"),
-        );
+- $tokens: reference to the associative array of custom tokens that
+  are available to be used in mailings and other contexts. This will
+  be an empty array unless an implementation of hook_civicrm_tokens
+  adds items to it. Items should be added in this format:
+
+```php
+$tokens['date'] = [
+  'date.date_short' => ts("Today's Date: short format"),
+  'date.date_med' => ts("Today's Date: med format"),
+  'date.date_long' => ts("Today's Date: long format"),
+];
+$tokens['party'] = [
+  'party.balloons' => ts("Number of balloons"),
+];
+```
 
 ## Returns
 
--   null
+- null
+
+## Example
+
+```php
+function customtokens_civicrm_tokens(&$tokens) {
+  $tokens['team'] = [
+    'team.team_number' => 'Team number',
+  ];
+}
+```