From f7b2fef0454a09a68b6707d475373ffea5f9f34a Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Sun, 15 Mar 2015 00:34:07 -0400
Subject: [PATCH] API - provide more metadata for generic actions

---
 api/v3/Generic.php          | 43 ++++++++++++++++++++++++-----
 api/v3/Generic/Getlist.php  | 54 +++++++++++++++++++++++++++++++++++++
 api/v3/Generic/Setvalue.php |  2 --
 3 files changed, 90 insertions(+), 9 deletions(-)

diff --git a/api/v3/Generic.php b/api/v3/Generic.php
index cef725e085..1f71a107d9 100644
--- a/api/v3/Generic.php
+++ b/api/v3/Generic.php
@@ -80,7 +80,7 @@ function civicrm_api3_generic_getfields($apiRequest) {
   if (!$action || $action == 'getvalue' || $action == 'getcount') {
     $action = 'get';
   }
-  // determines whether to use unique field names - seem comment block above
+  // determines whether to use unique field names - see comment block above
   $unique = TRUE;
   if (empty($apiOptions) && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
     && isset($action, $results[$entity . $subentity][$sequential])) {
@@ -123,23 +123,30 @@ function civicrm_api3_generic_getfields($apiRequest) {
       $metadata = array(
         'id' => array(
           'title' => $entity . ' ID',
-          'name' => 'id',
           'api.required' => 1,
           'api.aliases' => array($lowercase_entity . '_id'),
           'type' => CRM_Utils_Type::T_INT,
         ));
       break;
 
-    case 'getoptions':
+    // Note: adding setvalue case here instead of in a generic spec function because
+    // some APIs override the generic setvalue fn which causes the generic spec to be overlooked.
+    case 'setvalue':
       $metadata = array(
         'field' => array(
-          'name' => 'field',
           'title' => 'Field name',
           'api.required' => 1,
+          'type' => CRM_Utils_Type::T_STRING,
         ),
-        'context' => array(
-          'name' => 'context',
-          'title' => 'Context',
+        'id' => array(
+          'title' => $entity . ' ID',
+          'api.required' => 1,
+          'type' => CRM_Utils_Type::T_INT,
+        ),
+        'value' => array(
+          'title' => 'Value',
+          'description' => "Field value to set",
+          'api.required' => 1,
         ),
       );
       break;
@@ -345,6 +352,28 @@ function civicrm_api3_generic_getoptions($apiRequest) {
   return civicrm_api3_create_success($options, $apiRequest['params'], $apiRequest['entity'], 'getoptions');
 }
 
+/**
+ * Provide metadata for this generic action
+ *
+ * @param $params
+ * @param $apiRequest
+ */
+function _civicrm_api3_generic_getoptions_spec(&$params, $apiRequest) {
+  $contexts = array_combine(array_keys(CRM_Core_DAO::buildOptionsContext()), array_keys(CRM_Core_DAO::buildOptionsContext()));
+  $params += array(
+    'field' => array(
+      'title' => 'Field name',
+      'api.required' => 1,
+      'type' => CRM_Utils_Type::T_STRING,
+    ),
+    'context' => array(
+      'title' => 'Context',
+      'options' => !empty($apiRequest['sequential']) ? CRM_Utils_Array::makeNonAssociative($contexts) : $contexts,
+      'type' => CRM_Utils_Type::T_STRING,
+    ),
+  );
+}
+
 /**
  * Get metadata.
  *
diff --git a/api/v3/Generic/Getlist.php b/api/v3/Generic/Getlist.php
index 8a388ef1cb..fae25748f9 100644
--- a/api/v3/Generic/Getlist.php
+++ b/api/v3/Generic/Getlist.php
@@ -184,3 +184,57 @@ function _civicrm_api3_generic_getlist_output($result, $request) {
   }
   return $output;
 }
+
+/**
+ * Provide metadata for this api
+ *
+ * @param array $params
+ * @param array $apiRequest
+ */
+function _civicrm_api3_generic_getlist_spec(&$params, $apiRequest) {
+  $params += array(
+    'page_num' => array(
+      'title' => 'Page Number',
+      'description' => "Current page of a multi-page lookup",
+      'type' => CRM_Utils_Type::T_INT,
+    ),
+    'input' => array(
+      'title' => 'Search Input',
+      'description' => "String to search on",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+    'params' => array(
+      'title' => 'API Params',
+      'description' => "Additional filters to send to the {$apiRequest['entity']} API.",
+    ),
+    'extra' => array(
+      'title' => 'Extra',
+      'description' => 'Array of additional fields to return.',
+    ),
+    'image_field' => array(
+      'title' => 'Image Field',
+      'description' => "Field that this entity uses to store icons (usually automatic)",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+    'id_field' => array(
+      'title' => 'ID Field',
+      'description' => "Field that uniquely identifies this entity (usually automatic)",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+    'description_field' => array(
+      'title' => 'Description Field',
+      'description' => "Field that this entity uses to store summary text (usually automatic)",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+    'label_field' => array(
+      'title' => 'Search Field',
+      'description' => "Field to display as title of results (usually automatic)",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+    'search_field' => array(
+      'title' => 'Search Field',
+      'description' => "Field to search on (assumed to be the same as label field unless otherwise specified)",
+      'type' => CRM_Utils_Type::T_TEXT,
+    ),
+  );
+}
diff --git a/api/v3/Generic/Setvalue.php b/api/v3/Generic/Setvalue.php
index fd2223ad9e..3962fa2347 100644
--- a/api/v3/Generic/Setvalue.php
+++ b/api/v3/Generic/Setvalue.php
@@ -43,8 +43,6 @@
 function civicrm_api3_generic_setValue($apiRequest) {
   $entity = $apiRequest['entity'];
   $params = $apiRequest['params'];
-  // we can't use _spec, doesn't work with generic
-  civicrm_api3_verify_mandatory($params, NULL, array('id', 'field', 'value'));
   $id = $params['id'];
   if (!is_numeric($id)) {
     return civicrm_api3_create_error(ts('Please enter a number'), array(
-- 
2.25.1