3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2016 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
29 * @package CiviCRM_APIv3
33 * Generic api wrapper used for quicksearch and autocomplete.
35 * @param array $apiRequest
39 function civicrm_api3_generic_getList($apiRequest) {
40 $entity = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
41 $request = $apiRequest['params'];
42 $meta = civicrm_api3_generic_getfields(array('action' => 'get') +
$apiRequest, FALSE);
44 // Hey api, would you like to provide default values?
45 $fnName = "_civicrm_api3_{$entity}_getlist_defaults";
46 $defaults = function_exists($fnName) ?
$fnName($request) : array();
47 _civicrm_api3_generic_getList_defaults($entity, $request, $defaults, $meta['values']);
49 // Hey api, would you like to format the search params?
50 $fnName = "_civicrm_api3_{$entity}_getlist_params";
51 $fnName = function_exists($fnName) ?
$fnName : '_civicrm_api3_generic_getlist_params';
54 $request['params']['check_permissions'] = !empty($apiRequest['params']['check_permissions']);
55 $result = civicrm_api3($entity, 'get', $request['params']);
57 // Hey api, would you like to format the output?
58 $fnName = "_civicrm_api3_{$entity}_getlist_output";
59 $fnName = function_exists($fnName) ?
$fnName : '_civicrm_api3_generic_getlist_output';
60 $values = $fnName($result, $request, $entity, $meta['values']);
62 _civicrm_api3_generic_getlist_postprocess($result, $request, $values);
64 $output = array('page_num' => $request['page_num']);
66 // Limit is set for searching but not fetching by id
67 if (!empty($request['params']['options']['limit'])) {
68 // If we have an extra result then this is not the last page
69 $last = $request['params']['options']['limit'] - 1;
70 $output['more_results'] = isset($values[$last]);
71 unset($values[$last]);
74 return civicrm_api3_create_success($values, $request['params'], $entity, 'getlist', CRM_Core_DAO
::$_nullObject, $output);
78 * Set defaults for api.getlist.
80 * @param string $entity
81 * @param array $request
82 * @param array $apiDefaults
83 * @param array $fields
85 function _civicrm_api3_generic_getList_defaults($entity, &$request, $apiDefaults, $fields) {
86 $config = CRM_Core_Config
::singleton();
90 'image_field' => NULL,
91 'color_field' => isset($fields['color']) ?
'color' : NULL,
92 'id_field' => $entity == 'option_value' ?
'value' : 'id',
93 'description_field' => array(),
97 // Find main field from meta
98 foreach (array('sort_name', 'title', 'label', 'name', 'subject') as $field) {
99 if (isset($fields[$field])) {
100 $defaults['label_field'] = $defaults['search_field'] = $field;
104 // Find fields to be used for the description
105 foreach (array('description') as $field) {
106 if (isset($fields[$field])) {
107 $defaults['description_field'][] = $field;
110 $resultsPerPage = Civi
::settings()->get('search_autocomplete_count');
111 if (isset($request['params']) && isset($apiDefaults['params'])) {
112 $request['params'] +
= $apiDefaults['params'];
114 $request +
= $apiDefaults +
$defaults;
115 // Default api params
118 // Adding one extra result allows us to see if there are any more
119 'limit' => $resultsPerPage +
1,
120 // Because sql is zero-based
121 'offset' => ($request['page_num'] - 1) * $resultsPerPage,
122 'sort' => $request['label_field'],
126 // When searching e.g. autocomplete
127 if ($request['input']) {
128 $params[$request['search_field']] = array('LIKE' => ($config->includeWildCardInName ?
'%' : '') . $request['input'] . '%');
130 // When looking up a field e.g. displaying existing record
131 if (!empty($request['id'])) {
132 if (is_string($request['id']) && strpos($request['id'], ',')) {
133 $request['id'] = explode(',', trim($request['id'], ', '));
135 // Don't run into search limits when prefilling selection
136 $params['options']['limit'] = NULL;
137 unset($params['options']['offset'], $request['params']['options']['limit'], $request['params']['options']['offset']);
138 $params[$request['id_field']] = is_array($request['id']) ?
array('IN' => $request['id']) : $request['id'];
140 $request['params'] +
= $params;
144 * Fallback implementation of getlist_params. May be overridden by individual apis.
146 * @param array $request
148 function _civicrm_api3_generic_getlist_params(&$request) {
149 $fieldsToReturn = array($request['id_field'], $request['label_field']);
150 if (!empty($request['image_field'])) {
151 $fieldsToReturn[] = $request['image_field'];
153 if (!empty($request['color_field'])) {
154 $fieldsToReturn[] = $request['color_field'];
156 if (!empty($request['description_field'])) {
157 $fieldsToReturn = array_merge($fieldsToReturn, (array) $request['description_field']);
159 $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
163 * Fallback implementation of getlist_output. May be overridden by individual api functions.
165 * @param array $result
166 * @param array $request
167 * @param string $entity
168 * @param array $fields
172 function _civicrm_api3_generic_getlist_output($result, $request, $entity, $fields) {
174 if (!empty($result['values'])) {
175 foreach ($result['values'] as $row) {
177 'id' => $row[$request['id_field']],
178 'label' => $row[$request['label_field']],
180 if (!empty($request['description_field'])) {
181 $data['description'] = array();
182 foreach ((array) $request['description_field'] as $field) {
183 if (!empty($row[$field])) {
184 if (!isset($fields[$field]['pseudoconstant'])) {
185 $data['description'][] = $row[$field];
188 $data['description'][] = CRM_Core_PseudoConstant
::getLabel(
189 _civicrm_api3_get_BAO($entity),
197 if (!empty($request['image_field'])) {
198 $data['image'] = isset($row[$request['image_field']]) ?
$row[$request['image_field']] : '';
200 if (isset($row[$request['color_field']])) {
201 $data['color'] = $row[$request['color_field']];
210 * Common postprocess for getlist output
216 function _civicrm_api3_generic_getlist_postprocess($result, $request, &$values) {
218 foreach ($request['params'] as $field => $param) {
219 if (substr($field, 0, 4) === 'api.') {
223 if (!empty($result['values'])) {
224 foreach (array_values($result['values']) as $num => $row) {
225 foreach ($request['extra'] as $field) {
226 $values[$num]['extra'][$field] = isset($row[$field]) ?
$row[$field] : NULL;
228 foreach ($chains as $chain) {
229 $values[$num][$chain] = isset($row[$chain]) ?
$row[$chain] : NULL;
236 * Provide metadata for this api
238 * @param array $params
239 * @param array $apiRequest
241 function _civicrm_api3_generic_getlist_spec(&$params, $apiRequest) {
244 'title' => 'Page Number',
245 'description' => "Current page of a multi-page lookup",
246 'type' => CRM_Utils_Type
::T_INT
,
249 'title' => 'Search Input',
250 'description' => "String to search on",
251 'type' => CRM_Utils_Type
::T_TEXT
,
254 'title' => 'API Params',
255 'description' => "Additional filters to send to the {$apiRequest['entity']} API.",
259 'description' => 'Array of additional fields to return.',
261 'image_field' => array(
262 'title' => 'Image Field',
263 'description' => "Field that this entity uses to store icons (usually automatic)",
264 'type' => CRM_Utils_Type
::T_TEXT
,
267 'title' => 'ID Field',
268 'description' => "Field that uniquely identifies this entity (usually automatic)",
269 'type' => CRM_Utils_Type
::T_TEXT
,
271 'description_field' => array(
272 'title' => 'Description Field',
273 'description' => "Field that this entity uses to store summary text (usually automatic)",
274 'type' => CRM_Utils_Type
::T_TEXT
,
276 'label_field' => array(
277 'title' => 'Label Field',
278 'description' => "Field to display as title of results (usually automatic)",
279 'type' => CRM_Utils_Type
::T_TEXT
,
281 'search_field' => array(
282 'title' => 'Search Field',
283 'description' => "Field to search on (assumed to be the same as label field unless otherwise specified)",
284 'type' => CRM_Utils_Type
::T_TEXT
,