683fb44c24f10b07a0ca931b2edcc5a778cdc810
3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
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 'id_field' => $entity == 'option_value' ?
'value' : 'id',
92 'description_field' => array(),
96 // Find main field from meta
97 foreach (array('sort_name', 'title', 'label', 'name', 'subject') as $field) {
98 if (isset($fields[$field])) {
99 $defaults['label_field'] = $defaults['search_field'] = $field;
103 // Find fields to be used for the description
104 foreach (array('description') as $field) {
105 if (isset($fields[$field])) {
106 $defaults['description_field'][] = $field;
109 $resultsPerPage = Civi
::settings()->get('search_autocomplete_count');
110 if (isset($request['params']) && isset($apiDefaults['params'])) {
111 $request['params'] +
= $apiDefaults['params'];
113 $request +
= $apiDefaults +
$defaults;
114 // Default api params
117 // Adding one extra result allows us to see if there are any more
118 'limit' => $resultsPerPage +
1,
119 // Because sql is zero-based
120 'offset' => ($request['page_num'] - 1) * $resultsPerPage,
121 'sort' => $request['label_field'],
125 // When searching e.g. autocomplete
126 if ($request['input']) {
127 $params[$request['search_field']] = array('LIKE' => ($config->includeWildCardInName ?
'%' : '') . $request['input'] . '%');
129 // When looking up a field e.g. displaying existing record
130 if (!empty($request['id'])) {
131 if (is_string($request['id']) && strpos($request['id'], ',')) {
132 $request['id'] = explode(',', trim($request['id'], ', '));
134 // Don't run into search limits when prefilling selection
135 $params['options']['limit'] = NULL;
136 unset($params['options']['offset'], $request['params']['options']['limit'], $request['params']['options']['offset']);
137 $params[$request['id_field']] = is_array($request['id']) ?
array('IN' => $request['id']) : $request['id'];
139 $request['params'] +
= $params;
143 * Fallback implementation of getlist_params. May be overridden by individual apis.
145 * @param array $request
147 function _civicrm_api3_generic_getlist_params(&$request) {
148 $fieldsToReturn = array($request['id_field'], $request['label_field']);
149 if (!empty($request['image_field'])) {
150 $fieldsToReturn[] = $request['image_field'];
152 if (!empty($request['description_field'])) {
153 $fieldsToReturn = array_merge($fieldsToReturn, (array) $request['description_field']);
155 $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
159 * Fallback implementation of getlist_output. May be overridden by individual api functions.
161 * @param array $result
162 * @param array $request
163 * @param string $entity
164 * @param array $fields
168 function _civicrm_api3_generic_getlist_output($result, $request, $entity, $fields) {
170 if (!empty($result['values'])) {
171 foreach ($result['values'] as $row) {
173 'id' => $row[$request['id_field']],
174 'label' => $row[$request['label_field']],
176 if (!empty($request['description_field'])) {
177 $data['description'] = array();
178 foreach ((array) $request['description_field'] as $field) {
179 if (!empty($row[$field])) {
180 if (!isset($fields[$field]['pseudoconstant'])) {
181 $data['description'][] = $row[$field];
184 $data['description'][] = CRM_Core_PseudoConstant
::getLabel(
185 _civicrm_api3_get_BAO($entity),
193 if (!empty($request['image_field'])) {
194 $data['image'] = isset($row[$request['image_field']]) ?
$row[$request['image_field']] : '';
203 * Common postprocess for getlist output
209 function _civicrm_api3_generic_getlist_postprocess($result, $request, &$values) {
211 foreach ($request['params'] as $field => $param) {
212 if (substr($field, 0, 4) === 'api.') {
216 if (!empty($result['values'])) {
217 foreach (array_values($result['values']) as $num => $row) {
218 foreach ($request['extra'] as $field) {
219 $values[$num]['extra'][$field] = isset($row[$field]) ?
$row[$field] : NULL;
221 foreach ($chains as $chain) {
222 $values[$num][$chain] = isset($row[$chain]) ?
$row[$chain] : NULL;
229 * Provide metadata for this api
231 * @param array $params
232 * @param array $apiRequest
234 function _civicrm_api3_generic_getlist_spec(&$params, $apiRequest) {
237 'title' => 'Page Number',
238 'description' => "Current page of a multi-page lookup",
239 'type' => CRM_Utils_Type
::T_INT
,
242 'title' => 'Search Input',
243 'description' => "String to search on",
244 'type' => CRM_Utils_Type
::T_TEXT
,
247 'title' => 'API Params',
248 'description' => "Additional filters to send to the {$apiRequest['entity']} API.",
252 'description' => 'Array of additional fields to return.',
254 'image_field' => array(
255 'title' => 'Image Field',
256 'description' => "Field that this entity uses to store icons (usually automatic)",
257 'type' => CRM_Utils_Type
::T_TEXT
,
260 'title' => 'ID Field',
261 'description' => "Field that uniquely identifies this entity (usually automatic)",
262 'type' => CRM_Utils_Type
::T_TEXT
,
264 'description_field' => array(
265 'title' => 'Description Field',
266 'description' => "Field that this entity uses to store summary text (usually automatic)",
267 'type' => CRM_Utils_Type
::T_TEXT
,
269 'label_field' => array(
270 'title' => 'Search Field',
271 'description' => "Field to display as title of results (usually automatic)",
272 'type' => CRM_Utils_Type
::T_TEXT
,
274 'search_field' => array(
275 'title' => 'Search Field',
276 'description' => "Field to search on (assumed to be the same as label field unless otherwise specified)",
277 'type' => CRM_Utils_Type
::T_TEXT
,