3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * @package CiviCRM_APIv3
17 * Generic api wrapper used for quicksearch and autocomplete.
19 * @param array $apiRequest
23 function civicrm_api3_generic_getList($apiRequest) {
24 $entity = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
25 $request = $apiRequest['params'];
26 $meta = civicrm_api3_generic_getfields(['action' => 'get'] +
$apiRequest, FALSE);
28 // Hey api, would you like to provide default values?
29 $fnName = "_civicrm_api3_{$entity}_getlist_defaults";
30 $defaults = function_exists($fnName) ?
$fnName($request) : [];
31 _civicrm_api3_generic_getList_defaults($entity, $request, $defaults, $meta['values']);
33 // Hey api, would you like to format the search params?
34 $fnName = "_civicrm_api3_{$entity}_getlist_params";
35 $fnName = function_exists($fnName) ?
$fnName : '_civicrm_api3_generic_getlist_params';
38 $request['params']['check_permissions'] = !empty($apiRequest['params']['check_permissions']);
39 $result = civicrm_api3($entity, 'get', $request['params']);
41 // Hey api, would you like to format the output?
42 $fnName = "_civicrm_api3_{$entity}_getlist_output";
43 $fnName = function_exists($fnName) ?
$fnName : '_civicrm_api3_generic_getlist_output';
44 $values = $fnName($result, $request, $entity, $meta['values']);
46 _civicrm_api3_generic_getlist_postprocess($result, $request, $values);
48 $output = ['page_num' => $request['page_num']];
50 // Limit is set for searching but not fetching by id
51 if (!empty($request['params']['options']['limit'])) {
52 // If we have an extra result then this is not the last page
53 $last = $request['params']['options']['limit'] - 1;
54 $output['more_results'] = isset($values[$last]);
55 unset($values[$last]);
58 return civicrm_api3_create_success($values, $request['params'], $entity, 'getlist', CRM_Core_DAO
::$_nullObject, $output);
62 * Set defaults for api.getlist.
64 * @param string $entity
65 * @param array $request
66 * @param array $apiDefaults
67 * @param array $fields
69 function _civicrm_api3_generic_getList_defaults($entity, &$request, $apiDefaults, $fields) {
73 'image_field' => NULL,
74 'color_field' => isset($fields['color']) ?
'color' : NULL,
75 'id_field' => $entity == 'option_value' ?
'value' : 'id',
76 'description_field' => [],
77 'add_wildcard' => Civi
::settings()->get('includeWildCardInName'),
81 // Find main field from meta
82 foreach (['sort_name', 'title', 'label', 'name', 'subject'] as $field) {
83 if (isset($fields[$field])) {
84 $defaults['label_field'] = $defaults['search_field'] = $field;
88 // Find fields to be used for the description
89 foreach (['description'] as $field) {
90 if (isset($fields[$field])) {
91 $defaults['description_field'][] = $field;
94 $resultsPerPage = Civi
::settings()->get('search_autocomplete_count');
95 if (isset($request['params']) && isset($apiDefaults['params'])) {
96 $request['params'] +
= $apiDefaults['params'];
98 $request +
= $apiDefaults +
$defaults;
104 // When searching e.g. autocomplete
105 if ($request['input']) {
106 $params[$request['search_field']] = ['LIKE' => ($request['add_wildcard'] ?
'%' : '') . $request['input'] . '%'];
108 // When looking up a field e.g. displaying existing record
109 if (!empty($request['id'])) {
110 if (is_string($request['id']) && strpos($request['id'], ',')) {
111 $request['id'] = explode(',', trim($request['id'], ', '));
113 // Don't run into search limits when prefilling selection
114 $params['options']['limit'] = NULL;
115 unset($params['options']['offset'], $request['params']['options']['limit'], $request['params']['options']['offset']);
116 $params[$request['id_field']] = is_array($request['id']) ?
['IN' => $request['id']] : $request['id'];
118 $request['params'] +
= $params;
120 $request['params']['options'] +
= [
121 // Add pagination parameters
122 'sort' => $request['label_field'],
123 // Adding one extra result allows us to see if there are any more
124 'limit' => $resultsPerPage +
1,
125 // Because sql is zero-based
126 'offset' => ($request['page_num'] - 1) * $resultsPerPage,
131 * Fallback implementation of getlist_params. May be overridden by individual apis.
133 * @param array $request
135 function _civicrm_api3_generic_getlist_params(&$request) {
136 $fieldsToReturn = [$request['id_field'], $request['label_field']];
137 if (!empty($request['image_field'])) {
138 $fieldsToReturn[] = $request['image_field'];
140 if (!empty($request['color_field'])) {
141 $fieldsToReturn[] = $request['color_field'];
143 if (!empty($request['description_field'])) {
144 $fieldsToReturn = array_merge($fieldsToReturn, (array) $request['description_field']);
146 $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
150 * Fallback implementation of getlist_output. May be overridden by individual api functions.
152 * @param array $result
153 * @param array $request
154 * @param string $entity
155 * @param array $fields
159 function _civicrm_api3_generic_getlist_output($result, $request, $entity, $fields) {
161 if (!empty($result['values'])) {
162 foreach ($result['values'] as $row) {
164 'id' => $row[$request['id_field']],
165 'label' => $row[$request['label_field']],
167 if (!empty($request['description_field'])) {
168 $data['description'] = [];
169 foreach ((array) $request['description_field'] as $field) {
170 if (!empty($row[$field])) {
171 if (!isset($fields[$field]['pseudoconstant'])) {
172 $data['description'][] = $row[$field];
175 $data['description'][] = CRM_Core_PseudoConstant
::getLabel(
176 _civicrm_api3_get_BAO($entity),
184 if (!empty($request['image_field'])) {
185 $data['image'] = isset($row[$request['image_field']]) ?
$row[$request['image_field']] : '';
187 if (isset($row[$request['color_field']])) {
188 $data['color'] = $row[$request['color_field']];
197 * Common postprocess for getlist output
203 function _civicrm_api3_generic_getlist_postprocess($result, $request, &$values) {
205 foreach ($request['params'] as $field => $param) {
206 if (substr($field, 0, 4) === 'api.') {
210 if (!empty($result['values'])) {
211 foreach (array_values($result['values']) as $num => $row) {
212 foreach ($request['extra'] as $field) {
213 $values[$num]['extra'][$field] = isset($row[$field]) ?
$row[$field] : NULL;
215 foreach ($chains as $chain) {
216 $values[$num][$chain] = isset($row[$chain]) ?
$row[$chain] : NULL;
223 * Provide metadata for this api
225 * @param array $params
226 * @param array $apiRequest
228 function _civicrm_api3_generic_getlist_spec(&$params, $apiRequest) {
231 'title' => 'Page Number',
232 'description' => "Current page of a multi-page lookup",
233 'type' => CRM_Utils_Type
::T_INT
,
236 'title' => 'Search Input',
237 'description' => "String to search on",
238 'type' => CRM_Utils_Type
::T_TEXT
,
241 'title' => 'API Params',
242 'description' => "Additional filters to send to the {$apiRequest['entity']} API.",
246 'description' => 'Array of additional fields to return.',
249 'title' => 'Image Field',
250 'description' => "Field that this entity uses to store icons (usually automatic)",
251 'type' => CRM_Utils_Type
::T_TEXT
,
254 'title' => 'ID Field',
255 'description' => "Field that uniquely identifies this entity (usually automatic)",
256 'type' => CRM_Utils_Type
::T_TEXT
,
258 'description_field' => [
259 'title' => 'Description Field',
260 'description' => "Field that this entity uses to store summary text (usually automatic)",
261 'type' => CRM_Utils_Type
::T_TEXT
,
264 'title' => 'Label Field',
265 'description' => "Field to display as title of results (usually automatic)",
266 'type' => CRM_Utils_Type
::T_TEXT
,
269 'title' => 'Search Field',
270 'description' => "Field to search on (assumed to be the same as label field unless otherwise specified)",
271 'type' => CRM_Utils_Type
::T_TEXT
,