3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
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 * Base class for most search forms
31 class CRM_Core_Form_Search
extends CRM_Core_Form
{
34 * Are we forced to run a search
41 * Name of search button
45 protected $_searchButtonName;
48 * Name of action button
52 protected $_actionButtonName;
55 * Form values that we will be using
62 * Have we already done this search
69 * What context are we being invoked from
73 protected $_context = NULL;
76 * The list of tasks or actions that a searcher can perform on a result set.
80 protected $_taskList = array();
83 * Declare entity reference fields as they will need to be converted.
85 * The entity reference format looks like '2,3' whereas the Query object expects array(2, 3)
86 * or array('IN' => array(2, 3). The latter is the one we are moving towards standardising on.
90 protected $entityReferenceFields = array();
93 * Builds the list of tasks or actions that a searcher can perform on a result set.
95 * To modify the task list, child classes should alter $this->_taskList,
96 * preferably by extending this method.
100 protected function buildTaskList() {
101 return $this->_taskList
;
105 * Metadata for fields on the search form.
109 protected $searchFieldMetadata = [];
114 public function getSearchFieldMetadata() {
115 return $this->searchFieldMetadata
;
119 * @param array $searchFieldMetadata
121 public function addSearchFieldMetadata($searchFieldMetadata) {
122 $this->searchFieldMetadata
= array_merge($this->searchFieldMetadata
, $searchFieldMetadata);
126 * Common buildForm tasks required by all searches.
128 public function buildQuickform() {
129 CRM_Core_Resources
::singleton()
130 ->addScriptFile('civicrm', 'js/crm.searchForm.js', 1, 'html-header')
131 ->addStyleFile('civicrm', 'css/searchForm.css', 1, 'html-header');
133 $this->addButtons(array(
136 'name' => ts('Search'),
141 $this->addClass('crm-search-form');
143 $tasks = $this->buildTaskList();
144 $this->addTaskMenu($tasks);
148 * Add any fields described in metadata to the form.
150 * The goal is to describe all fields in metadata and handle from metadata rather
151 * than existing ad hoc handling.
153 public function addFormFieldsFromMetadata() {
154 $this->_action
= CRM_Core_Action
::ADVANCED
;
155 foreach ($this->getSearchFieldMetadata() as $entity => $fields) {
156 foreach ($fields as $fieldName => $fieldSpec) {
157 if ($fieldSpec['type'] === CRM_Utils_Type
::T_DATE
) {
158 // Assuming time is false for now as we are not checking for date-time fields as yet.
159 $this->addDatePickerRange($fieldName, $fieldSpec['title'], FALSE);
162 $this->addField($fieldName, ['entity' => $entity]);
169 * Get the validation rule to apply to a function.
171 * Alphanumeric is designed to always be safe & for now we just return
172 * that but in future we can use tighter rules for types like int, bool etc.
174 * @param string $entity
175 * @param string $fieldName
179 protected function getValidationTypeForField($entity, $fieldName) {
180 switch ($this->getSearchFieldMetadata()[$entity][$fieldName]['type']) {
181 case CRM_Utils_Type
::T_BOOLEAN
:
184 case CRM_Utils_Type
::T_INT
:
185 return 'CommaSeparatedIntegers';
188 return 'Alphanumeric';
193 * Get the defaults for the entity for any fields described in metadata.
195 * @param string $entity
199 protected function getEntityDefaults($entity) {
201 foreach ($this->getSearchFieldMetadata()[$entity] as $fieldSpec) {
202 if (empty($_POST[$fieldSpec['name']])) {
203 $value = CRM_Utils_Request
::retrieveValue($fieldSpec['name'], $this->getValidationTypeForField($entity, $fieldSpec['name']), FALSE, NULL, 'GET');
204 if ($value !== FALSE) {
205 $defaults[$fieldSpec['name']] = $value;
213 * Add checkboxes for each row plus a master checkbox.
217 public function addRowSelectors($rows) {
218 $this->addElement('checkbox', 'toggleSelect', NULL, NULL, array('class' => 'select-rows'));
220 foreach ($rows as $row) {
221 if (CRM_Utils_Array
::value('checkbox', $row)) {
222 $this->addElement('checkbox', $row['checkbox'], NULL, NULL, array('class' => 'select-row'));
229 * Add actions menu to search results form.
231 * @param array $tasks
233 public function addTaskMenu($tasks) {
234 $taskMetaData = array();
235 foreach ($tasks as $key => $task) {
236 $taskMetaData[$key] = array('title' => $task);
238 parent
::addTaskMenu($taskMetaData);
242 * Add the sort-name field to the form.
244 * There is a setting to determine whether email is included in the search & we look this up to determine
245 * which text to choose.
247 * Note that for translation purposes the full string works better than using 'prefix' hence we use override-able functions
248 * to define the string.
250 protected function addSortNameField() {
254 civicrm_api3('setting', 'getvalue', array('name' => 'includeEmailInName', 'group' => 'Search Preferences')) ?
$this->getSortNameLabelWithEmail() : $this->getSortNameLabelWithOutEmail(),
255 CRM_Core_DAO
::getAttribute('CRM_Contact_DAO_Contact', 'sort_name')
260 * Get the label for the sortName field if email searching is on.
262 * (email searching is a setting under search preferences).
266 protected function getSortNameLabelWithEmail() {
267 return ts('Name or Email');
271 * Get the label for the sortName field if email searching is off.
273 * (email searching is a setting under search preferences).
277 protected function getSortNameLabelWithOutEmail() {
282 * Explicitly declare the form context for addField().
284 public function getDefaultContext() {
289 * Add generic fields that specify the contact.
291 protected function addContactSearchFields() {
292 if (!$this->isFormInViewOrEditMode()) {
295 $this->addSortNameField();
297 $this->_group
= CRM_Core_PseudoConstant
::nestedGroup();
299 $this->add('select', 'group', $this->getGroupLabel(), $this->_group
, FALSE,
302 'multiple' => 'multiple',
303 'class' => 'crm-select2',
308 $contactTags = CRM_Core_BAO_Tag
::getTags();
310 $this->add('select', 'contact_tags', $this->getTagLabel(), $contactTags, FALSE,
312 'id' => 'contact_tags',
313 'multiple' => 'multiple',
314 'class' => 'crm-select2',
318 $this->addField('contact_type', array('entity' => 'Contact'));
320 if (CRM_Core_Permission
::check('access deleted contacts') && Civi
::settings()->get('contact_undelete')) {
321 $this->addElement('checkbox', 'deleted_contacts', ts('Search in Trash') . '<br />' . ts('(deleted contacts)'));
327 * we allow the controller to set force/reset externally, useful when we are being
328 * driven by the wizard framework
330 protected function loadStandardSearchOptionsFromUrl() {
331 $this->_reset
= CRM_Utils_Request
::retrieve('reset', 'Boolean');
332 $this->_force
= CRM_Utils_Request
::retrieve('force', 'Boolean', $this, FALSE);
333 $this->_limit
= CRM_Utils_Request
::retrieve('limit', 'Positive', $this);
334 $this->_context
= CRM_Utils_Request
::retrieve('context', 'Alphanumeric', $this, FALSE, 'search');
335 $this->_ssID
= CRM_Utils_Request
::retrieve('ssID', 'Positive', $this);
336 $this->assign("context", $this->_context
);
340 * Get user submitted values.
342 * Get it from controller only if form has been submitted, else preProcess has set this
344 protected function loadFormValues() {
345 if (!empty($_POST) && !$this->controller
->isModal()) {
346 $this->_formValues
= $this->controller
->exportValues($this->_name
);
349 $this->_formValues
= $this->get('formValues');
352 if (empty($this->_formValues
)) {
353 if (isset($this->_ssID
)) {
354 $this->_formValues
= CRM_Contact_BAO_SavedSearch
::getFormValues($this->_ssID
);