Cleanup Mailing.gettokens api and add unit test

diff --git a/CRM/Mailing/Info.php b/CRM/Mailing/Info.php
index 9732035b8127a822af87696ceadbb8cf179e0330..69b6908d250b81da0429f2e25c011c438133249d 100644 (file)
--- a/CRM/Mailing/Info.php
+++ b/CRM/Mailing/Info.php
@@ -126,7 +126,7 @@ class CRM_Mailing_Info extends CRM_Core_Component_Info {
       ));
     }
     $mailGrp = civicrm_api3('MailingGroup', 'get', array());
-    $mailTokens = civicrm_api3('Mailing', 'get_token', array('usage' => 'Mailing'));
+    $mailTokens = civicrm_api3('Mailing', 'gettokens', array('entity' => array('contact', 'mailing'), 'sequential' => 1));
     $fromAddress = civicrm_api3('OptionGroup', 'get', array(
       'sequential' => 1,
       'name' => "from_email_address",
@@ -143,7 +143,7 @@ class CRM_Mailing_Info extends CRM_Core_Component_Info {
         'mesTemplate' => array_values($mesTemplate['values']),
         'emailAdd' => array_values($emailAdd['values']),
         'mailGrp' => array_values($mailGrp['values']),
-        'mailTokens' => array_values($mailTokens),
+        'mailTokens' => $mailTokens['values'],
         'contactid' => $contactID,
         'requiredTokens' => CRM_Utils_Token::getRequiredTokens(),
         'enableReplyTo' => isset($config->replyTo) ? $config->replyTo : 0,

diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php
index 71fb134ad77218cdd4eaf15a2527135def45dab4..d1dfbdc639f6ee813bec3c84596aa1f6901d3e8a 100755 (executable)
--- a/api/v3/Mailing.php
+++ b/api/v3/Mailing.php
@@ -70,29 +70,42 @@ function civicrm_api3_mailing_create($params) {
  * @return array
  * @throws \API_Exception
  */
-function civicrm_api3_mailing_get_token($params) {
-  if (!array_key_exists("usage", $params)) {
-    throw new API_Exception('Mandatory keys missing from params array: entity');
+function civicrm_api3_mailing_gettokens($params) {
+  $tokens = array();
+  foreach ((array) $params['entity'] as $ent) {
+    $func = $ent . 'Tokens';
+    if (!method_exists('CRM_Core_SelectValues', $func)) {
+      throw new API_Exception('Unknown token entity: ' . $ent);
+    }
+    $tokens = array_merge(CRM_Core_SelectValues::$func(), $tokens);
   }
-
-  $tokens = CRM_Core_SelectValues::contactTokens();
-  switch ($params['usage']) {
-    case 'Mailing':
-      $tokens = array_merge(CRM_Core_SelectValues::mailingTokens(), $tokens);
-      break;
-
-    case 'ScheduleEventReminder':
-      $tokens = array_merge(CRM_Core_SelectValues::activityTokens(), $tokens);
-      $tokens = array_merge(CRM_Core_SelectValues::eventTokens(), $tokens);
-      $tokens = array_merge(CRM_Core_SelectValues::membershipTokens(), $tokens);
-      break;
-
-    case 'ManageEventScheduleReminder':
-      $tokens = array_merge(CRM_Core_SelectValues::eventTokens(), $tokens);
-      break;
+  if (!empty($params['sequential'])) {
+    $tokens = CRM_Utils_Token::formatTokensForDisplay($tokens);
   }
+  return civicrm_api3_create_success($tokens, $params, 'Mailing', 'gettokens');
+}
 
-  return CRM_Utils_Token::formatTokensForDisplay($tokens);
+/**
+ * Adjust Metadata for Create action.
+ *
+ * The metadata is used for setting defaults, documentation & validation.
+ *
+ * @param array $params
+ *   Array of parameters determined by getfields.
+ */
+function _civicrm_api3_mailing_gettokens_spec(&$params) {
+  $params['entity'] = array(
+    'api.default' => array('contact'),
+    'api.required' => 1,
+    'title' => 'Entity',
+    'options' => array(),
+  );
+  foreach (get_class_methods('CRM_Core_SelectValues') as $func) {
+    if (strpos($func, 'Tokens')) {
+      $ent = 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
new file mode 100644 (file)
index 0000000..279d84f
--- /dev/null
+++ b/api/v3/examples/Mailing/GetTokens.php
@@ -0,0 +1,158 @@
+<?php
+/**
+ * Test Generated example demonstrating the Mailing.gettokens API.
+ *
+ * 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
+ *   API result array
+ */
+function mailing_gettokens_example() {
+  $params = array(
+    'entity' => array(
+      '0' => 'contact',
+      '1' => 'mailing',
+    ),
+  );
+
+  try{
+    $result = civicrm_api3('Mailing', 'gettokens', $params);
+  }
+  catch (CiviCRM_API3_Exception $e) {
+    // Handle error here.
+    $errorMessage = $e->getMessage();
+    $errorCode = $e->getErrorCode();
+    $errorData = $e->getExtraParams();
+    return array(
+      'error' => $errorMessage,
+      'error_code' => $errorCode,
+      'error_data' => $errorData,
+    );
+  }
+
+  return $result;
+}
+
+/**
+ * Function returns array of result expected from previous function.
+ *
+ * @return array
+ *   API result array
+ */
+function mailing_gettokens_expectedresult() {
+
+  $expectedResult = array(
+    'is_error' => 0,
+    'version' => 3,
+    'count' => 82,
+    'values' => array(
+      '{action.unsubscribe}' => 'Unsubscribe via email',
+      '{action.unsubscribeUrl}' => 'Unsubscribe via web page',
+      '{action.resubscribe}' => 'Resubscribe via email',
+      '{action.resubscribeUrl}' => 'Resubscribe via web page',
+      '{action.optOut}' => 'Opt out via email',
+      '{action.optOutUrl}' => 'Opt out via web page',
+      '{action.forward}' => 'Forward this email (link)',
+      '{action.reply}' => 'Reply to this email (link)',
+      '{action.subscribeUrl}' => 'Subscribe via web page',
+      '{domain.name}' => 'Domain name',
+      '{domain.address}' => 'Domain (organization) address',
+      '{domain.phone}' => 'Domain (organization) phone',
+      '{domain.email}' => 'Domain (organization) email',
+      '{mailing.name}' => 'Mailing name',
+      '{mailing.group}' => 'Mailing group',
+      '{mailing.viewUrl}' => 'Mailing permalink',
+      '{contact.contact_type}' => 'Contact Type',
+      '{contact.do_not_email}' => 'Do Not Email',
+      '{contact.do_not_phone}' => 'Do Not Phone',
+      '{contact.do_not_mail}' => 'Do Not Mail',
+      '{contact.do_not_sms}' => 'Do Not Sms',
+      '{contact.do_not_trade}' => 'Do Not Trade',
+      '{contact.is_opt_out}' => 'No Bulk Emails (User Opt Out)',
+      '{contact.external_identifier}' => 'External Identifier',
+      '{contact.sort_name}' => 'Sort Name',
+      '{contact.display_name}' => 'Display Name',
+      '{contact.nick_name}' => 'Nickname',
+      '{contact.image_URL}' => 'Image Url',
+      '{contact.preferred_communication_method}' => 'Preferred Communication Method',
+      '{contact.preferred_language}' => 'Preferred Language',
+      '{contact.preferred_mail_format}' => 'Preferred Mail Format',
+      '{contact.hash}' => 'Contact Hash',
+      '{contact.contact_source}' => 'Source of Contact Data',
+      '{contact.first_name}' => 'First Name',
+      '{contact.middle_name}' => 'Middle Name',
+      '{contact.last_name}' => 'Last Name',
+      '{contact.individual_prefix}' => 'Individual Prefix',
+      '{contact.individual_suffix}' => 'Individual Suffix',
+      '{contact.formal_title}' => 'Formal Title',
+      '{contact.communication_style}' => 'Communication Style',
+      '{contact.job_title}' => 'Job Title',
+      '{contact.gender}' => 'Gender',
+      '{contact.birth_date}' => 'Birth Date',
+      '{contact.current_employer_id}' => 'Current Employer ID',
+      '{contact.contact_is_deleted}' => 'Contact is in Trash',
+      '{contact.created_date}' => 'Created Date',
+      '{contact.modified_date}' => 'Modified Date',
+      '{contact.addressee}' => 'Addressee',
+      '{contact.email_greeting}' => 'Email Greeting',
+      '{contact.postal_greeting}' => 'Postal Greeting',
+      '{contact.current_employer}' => 'Current Employer',
+      '{contact.location_type}' => 'Location Type',
+      '{contact.street_address}' => 'Street Address',
+      '{contact.street_number}' => 'Street Number',
+      '{contact.street_number_suffix}' => 'Street Number Suffix',
+      '{contact.street_name}' => 'Street Name',
+      '{contact.street_unit}' => 'Street Unit',
+      '{contact.supplemental_address_1}' => 'Supplemental Address 1',
+      '{contact.supplemental_address_2}' => 'Supplemental Address 2',
+      '{contact.city}' => 'City',
+      '{contact.postal_code_suffix}' => 'Postal Code Suffix',
+      '{contact.postal_code}' => 'Postal Code',
+      '{contact.geo_code_1}' => 'Latitude',
+      '{contact.geo_code_2}' => 'Longitude',
+      '{contact.address_name}' => 'Address Name',
+      '{contact.master_id}' => 'Master Address Belongs To',
+      '{contact.county}' => 'County',
+      '{contact.state_province}' => 'State',
+      '{contact.country}' => 'Country',
+      '{contact.phone}' => 'Phone',
+      '{contact.phone_ext}' => 'Phone Extension',
+      '{contact.email}' => 'Email',
+      '{contact.on_hold}' => 'On Hold',
+      '{contact.signature_text}' => 'Signature Text',
+      '{contact.signature_html}' => 'Signature Html',
+      '{contact.im_provider}' => 'IM Provider',
+      '{contact.im}' => 'IM Screen Name',
+      '{contact.openid}' => 'OpenID',
+      '{contact.world_region}' => 'World Region',
+      '{contact.url}' => 'Website',
+      '{contact.checksum}' => 'Checksum',
+      '{contact.contact_id}' => 'Internal Contact ID',
+    ),
+  );
+
+  return $expectedResult;
+}
+
+/*
+* This example has been generated from the API test suite.
+* The test that created it is called "testMailGetTokens"
+* and can be found at:
+* https://github.com/civicrm/civicrm-core/blob/master/tests/phpunit/api/v3/MailingTest.php
+*
+* You can see the outcome of the API tests at
+* https://test.civicrm.org/job/CiviCRM-master-git/
+*
+* To Learn about the API read
+* http://wiki.civicrm.org/confluence/display/CRMDOC/Using+the+API
+*
+* Browse the api on your own site with the api explorer
+* http://MYSITE.ORG/path/to/civicrm/api
+*
+* Read more about testing here
+* http://wiki.civicrm.org/confluence/display/CRM/Testing
+*
+* API Standards documentation:
+* http://wiki.civicrm.org/confluence/display/CRM/API+Architecture+Standards
+*/

diff --git a/tests/phpunit/api/v3/MailingTest.php b/tests/phpunit/api/v3/MailingTest.php
index 0c33e8f0bbae204e96e73ac19092b77b11995c87..e9405cb2e9f10a97750a72f956b7d13549fbe73b 100755 (executable)
--- a/tests/phpunit/api/v3/MailingTest.php
+++ b/tests/phpunit/api/v3/MailingTest.php
@@ -496,6 +496,16 @@ SELECT event_queue_id, time_stamp FROM mail_{$type}_temp";
     $this->assertAPIDeleted($this->_entity, $result['id']);
   }
 
+  /**
+   * Test Mailing.gettokens.
+   */
+  public function testMailGetTokens() {
+    $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);
+  }
+
   //@ todo tests below here are all failure tests which are not hugely useful - need success tests
 
   //------------ civicrm_mailing_event_bounce methods------------