From 9950a1c94602362c958a3233dcaf021da8c850a6 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Tue, 24 Feb 2015 09:54:16 -0500
Subject: [PATCH] Mailing.gettokens api - Additional improvements

---
 CRM/Core/SelectValues.php             |  2 +-
 CRM/Utils/Token.php                   |  1 +
 api/v3/Mailing.php                    | 11 ++++++++---
 api/v3/examples/Mailing/GetTokens.php |  6 +++---
 tests/phpunit/api/v3/MailingTest.php  | 11 ++++++++---
 5 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/CRM/Core/SelectValues.php b/CRM/Core/SelectValues.php
index 2e30aafd67..b7273e4350 100644
--- a/CRM/Core/SelectValues.php
+++ b/CRM/Core/SelectValues.php
@@ -617,7 +617,7 @@ class CRM_Core_SelectValues {
         }
       }
 
-      // might as well get all the hook tokens to
+      // Get all the hook tokens too
       $hookTokens = array();
       CRM_Utils_Hook::tokens($hookTokens);
       foreach ($hookTokens as $tokenValues) {
diff --git a/CRM/Utils/Token.php b/CRM/Utils/Token.php
index b3ebfd7f53..6d94019636 100644
--- a/CRM/Utils/Token.php
+++ b/CRM/Utils/Token.php
@@ -1808,6 +1808,7 @@ class CRM_Utils_Token {
 
   /**
    * Formats a token list for the select2 widget
+   *
    * @param $tokens
    * @return array
    */
diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index 22fe9bcc52..d97176c1e7 100755
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -63,9 +63,13 @@ function civicrm_api3_mailing_create($params) {
 }
 
 /**
- * Get mailing token.
+ * Get tokens for one or more entity type
+ *
+ * Output will be formatted either as a flat list,
+ * or pass sequential=1 to retrieve as a hierarchy formatted for select2.
  *
  * @param array $params
+ *   Should contain an array of entities to retrieve tokens for.
  *
  * @return array
  * @throws \API_Exception
@@ -73,7 +77,7 @@ function civicrm_api3_mailing_create($params) {
 function civicrm_api3_mailing_gettokens($params) {
   $tokens = array();
   foreach ((array) $params['entity'] as $ent) {
-    $func = $ent . 'Tokens';
+    $func = lcfirst($ent) . 'Tokens';
     if (!method_exists('CRM_Core_SelectValues', $func)) {
       throw new API_Exception('Unknown token entity: ' . $ent);
     }
@@ -101,9 +105,10 @@ function _civicrm_api3_mailing_gettokens_spec(&$params) {
     'title' => 'Entity',
     'options' => array(),
   );
+  // Fetch a list of token functions and format to look like entity names
   foreach (get_class_methods('CRM_Core_SelectValues') as $func) {
     if (strpos($func, 'Tokens')) {
-      $ent = str_replace('Tokens', '', $func);
+      $ent = ucfirst(str_replace('Tokens', '', $func));
       $params['entity']['options'][$ent] = $ent;
     }
   }
diff --git a/api/v3/examples/Mailing/GetTokens.php b/api/v3/examples/Mailing/GetTokens.php
index 279d84f20f..8e100bedf1 100644
--- a/api/v3/examples/Mailing/GetTokens.php
+++ b/api/v3/examples/Mailing/GetTokens.php
@@ -2,7 +2,7 @@
 /**
  * Test Generated example demonstrating the Mailing.gettokens API.
  *
- * Demonstrates fetching tokens for one or more entities (in this case "contact" and "mailing").
+ * Demonstrates fetching tokens for one or more entities (in this case "Contact" and "Mailing").
  * Optionally pass sequential=1 to have output ready-formatted for the select2 widget.
  *
  * @return array
@@ -11,8 +11,8 @@
 function mailing_gettokens_example() {
   $params = array(
     'entity' => array(
-      '0' => 'contact',
-      '1' => 'mailing',
+      '0' => 'Contact',
+      '1' => 'Mailing',
     ),
   );
 
diff --git a/tests/phpunit/api/v3/MailingTest.php b/tests/phpunit/api/v3/MailingTest.php
index e9405cb2e9..fff3c7b597 100755
--- a/tests/phpunit/api/v3/MailingTest.php
+++ b/tests/phpunit/api/v3/MailingTest.php
@@ -500,10 +500,15 @@ SELECT event_queue_id, time_stamp FROM mail_{$type}_temp";
    * Test Mailing.gettokens.
    */
   public function testMailGetTokens() {
-    $description = "Demonstrates fetching tokens for one or more entities (in this case \"contact\" and \"mailing\").
+    $description = "Demonstrates fetching tokens for one or more entities (in this case \"Contact\" and \"Mailing\").
       Optionally pass sequential=1 to have output ready-formatted for the select2 widget.";
-    $result = $this->callAPIAndDocument($this->_entity, 'gettokens', array('entity' => array('contact', 'mailing')), __FUNCTION__, __FILE__, $description);
-    $this->assertContains('Contact Type', $result);
+    $result = $this->callAPIAndDocument($this->_entity, 'gettokens', array('entity' => array('Contact', 'Mailing')), __FUNCTION__, __FILE__, $description);
+    $this->assertContains('Contact Type', $result['values']);
+
+    // Check that passing "sequential" correctly outputs a hierarchical array
+    $result = $this->callAPISuccess($this->_entity, 'gettokens', array('entity' => 'contact', 'sequential' => 1));
+    $this->assertArrayHasKey('text', $result['values'][0]);
+    $this->assertArrayHasKey('id', $result['values'][0]['children'][0]);
   }
 
   //@ todo tests below here are all failure tests which are not hugely useful - need success tests
-- 
2.25.1