api/v3/Generic/Getlist.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5 | CiviCRM version 4.4                                                |
   6 +--------------------------------------------------------------------+
   7 | Copyright CiviCRM LLC (c) 2004-2013                                |
   8 +--------------------------------------------------------------------+
   9 | This file is a part of CiviCRM.                                    |
  10 |                                                                    |
  11 | CiviCRM is free software; you can copy, modify, and distribute it  |
  12 | under the terms of the GNU Affero General Public License           |
  13 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14 |                                                                    |
  15 | CiviCRM is distributed in the hope that it will be useful, but     |
  16 | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18 | See the GNU Affero General Public License for more details.        |
  19 |                                                                    |
  20 | You should have received a copy of the GNU Affero General Public   |
  21 | License and the CiviCRM Licensing Exception along                  |
  22 | with this program; if not, contact CiviCRM LLC                     |
  23 | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24 | GNU Affero General Public License or the licensing of CiviCRM,     |
  25 | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26 +--------------------------------------------------------------------+
  27 */
  28 /**
  29  * Generic api wrapper used for quicksearch and autocomplete
  30  *
  31  * @param $apiRequest array
  32  * @return mixed
  33  */
  34 function civicrm_api3_generic_getList($apiRequest) {
  35   $entity = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
  36   $request = $apiRequest['params'];
  37
  38   _civicrm_api3_generic_getList_defaults($entity, $request);
  39
  40   // Hey api, would you like to format the search params?
  41   $fnName = "_civicrm_api3_{$entity}_getlist_params";
  42   $fnName = function_exists($fnName) ? $fnName : '_civicrm_api3_generic_getlist_params';
  43   $fnName($request);
  44
  45   $request['params']['check_permissions'] = !empty($apiRequest['params']['check_permissions']);
  46   $result = civicrm_api3($entity, 'get', $request['params']);
  47
  48   // Hey api, would you like to format the output?
  49   $fnName = "_civicrm_api3_{$entity}_getlist_output";
  50   $fnName = function_exists($fnName) ? $fnName : '_civicrm_api3_generic_getlist_output';
  51   $values = $fnName($result, $request);
  52
  53   $last = $request['params']['limit'] - 1;
  54   $output = array(
  55     // If we have an extra result then this is not the last page
  56     'more_results' => isset($values[$last]),
  57     'page_num' => $request['page_num'],
  58   );
  59   unset($values[$last]);
  60
  61   return civicrm_api3_create_success($values, $request['params'], $entity, 'getlist', CRM_Core_DAO::$_nullObject, $output);
  62 }
  63
  64 /**
  65  * Set defaults for api.getlist
  66  *
  67  * @param $entity string
  68  * @param $request array
  69  */
  70 function _civicrm_api3_generic_getList_defaults($entity, &$request) {
  71   $config = CRM_Core_Config::singleton();
  72   $fields = _civicrm_api_get_fields($entity);
  73   $defaults = array(
  74     'page_num' => 1,
  75     'input' => '',
  76     'image_field' => NULL,
  77     'id_field' => $entity == 'option_value' ? 'value' : 'id',
  78     'description_field' => array(),
  79     'params' => array(),
  80     'extra' => array(),
  81   );
  82   // Find main field from meta
  83   foreach (array('sort_name', 'title', 'label', 'name') as $field) {
  84     if (isset($fields[$field])) {
  85       $defaults['label_field'] = $defaults['search_field'] = $field;
  86       break;
  87     }
  88   }
  89   // Find fields to be used for the description
  90   foreach (array('description') as $field) {
  91     if (isset($fields[$field])) {
  92       $defaults['description_field'][] = $field;
  93     }
  94   }
  95   $resultsPerPage = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'search_autocomplete_count', NULL, 10);
  96   $request += $defaults;
  97   // Default api params
  98   $params = array(
  99     'options' => array(
 100       // Adding one extra result allows us to see if there are any more
 101       'limit' => $resultsPerPage + 1,
 102       // Because sql is zero-based
 103       'offset' => ($request['page_num'] - 1) * $resultsPerPage,
 104       'sort' => $request['label_field'],
 105     ),
 106     'sequential' => 1,
 107   );
 108   // When searching e.g. autocomplete
 109   if ($request['input']) {
 110     $params[$request['search_field']] = array('LIKE' => ($config->includeWildCardInName ? '%' : '') . $request['input'] . '%');
 111   }
 112   // When looking up a field e.g. displaying existing record
 113   if (!empty($request['id'])) {
 114     if (is_string($request['id']) && strpos(',', $request['id'])) {
 115       $request['id'] = explode(',', $request['id']);
 116     }
 117     $params[$request['id_field']] = is_array($request['id']) ? array('IN' => $request['id']) : $request['id'];
 118   }
 119   $request['params'] += $params;
 120 }
 121
 122 /**
 123  * Fallback implementation of getlist_params. May be overridden by individual apis
 124  *
 125  * @param $request array
 126  */
 127 function _civicrm_api3_generic_getlist_params(&$request) {
 128   $fieldsToReturn = array($request['id_field'], $request['label_field']);
 129   if (!empty($request['image_field'])) {
 130     $fieldsToReturn[] = $request['image_field'];
 131   }
 132   if (!empty($request['description_field'])) {
 133     $fieldsToReturn = array_merge($fieldsToReturn, (array) $request['description_field']);
 134   }
 135   $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
 136 }
 137
 138 /**
 139  * Fallback implementation of getlist_output. May be overridden by individual apis
 140  *
 141  * @param $result array
 142  * @param $request array
 143  *
 144  * @return array
 145  */
 146 function _civicrm_api3_generic_getlist_output($result, $request) {
 147   $output = array();
 148   if (!empty($result['values'])) {
 149     foreach ($result['values'] as $row) {
 150       $data = array(
 151         'id' => $row[$request['id_field']],
 152         'label' => $row[$request['label_field']],
 153       );
 154       if (!empty($request['description_field'])) {
 155         $data['description'] = array();
 156         foreach ((array) $request['description_field'] as $field) {
 157           if (!empty($row[$field])) {
 158             $data['description'][] = $row[$field];
 159           }
 160         }
 161       };
 162       if (!empty($request['image_field'])) {
 163         $data['image'] = isset($row[$request['image_field']]) ? $row[$request['image_field']] : '';
 164       }
 165       foreach ($request['extra'] as $field) {
 166         $data['extra'][$field] = isset($row[$field]) ? $row[$field] : NULL;
 167       }
 168       $output[] = $data;
 169     }
 170   }
 171   return $output;
 172 }