CRM/Core/Form/Search.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  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.   |
  13  |                                                                    |
  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.        |
  18  |                                                                    |
  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  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * Base class for most search forms
  30  */
  31 class CRM_Core_Form_Search extends CRM_Core_Form {
  32
  33   /**
  34    * Are we forced to run a search
  35    *
  36    * @var int
  37    */
  38   protected $_force;
  39
  40   /**
  41    * Name of search button
  42    *
  43    * @var string
  44    */
  45   protected $_searchButtonName;
  46
  47   /**
  48    * Name of action button
  49    *
  50    * @var string
  51    */
  52   protected $_actionButtonName;
  53
  54   /**
  55    * Form values that we will be using
  56    *
  57    * @var array
  58    */
  59   public $_formValues;
  60
  61   /**
  62    * Have we already done this search
  63    *
  64    * @var bool
  65    */
  66   protected $_done;
  67
  68   /**
  69    * What context are we being invoked from
  70    *
  71    * @var string
  72    */
  73   protected $_context = NULL;
  74
  75   /**
  76    * The list of tasks or actions that a searcher can perform on a result set.
  77    *
  78    * @var array
  79    */
  80   protected $_taskList = [];
  81
  82   /**
  83    * Declare entity reference fields as they will need to be converted.
  84    *
  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.
  87    *
  88    * @var array
  89    */
  90   protected $entityReferenceFields = [];
  91
  92   /**
  93    * Builds the list of tasks or actions that a searcher can perform on a result set.
  94    *
  95    * To modify the task list, child classes should alter $this->_taskList,
  96    * preferably by extending this method.
  97    *
  98    * @return array
  99    */
 100   protected function buildTaskList() {
 101     return $this->_taskList;
 102   }
 103
 104   /**
 105    * Metadata for fields on the search form.
 106    *
 107    * @var array
 108    */
 109   protected $searchFieldMetadata = [];
 110
 111   /**
 112    * @return array
 113    */
 114   public function getSearchFieldMetadata() {
 115     return $this->searchFieldMetadata;
 116   }
 117
 118   /**
 119    * @param array $searchFieldMetadata
 120    */
 121   public function addSearchFieldMetadata($searchFieldMetadata) {
 122     $this->searchFieldMetadata = array_merge($this->searchFieldMetadata, $searchFieldMetadata);
 123   }
 124
 125   /**
 126    * Common buildForm tasks required by all searches.
 127    */
 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');
 132
 133     $this->addButtons([
 134       [
 135         'type' => 'refresh',
 136         'name' => ts('Search'),
 137         'isDefault' => TRUE,
 138       ],
 139     ]);
 140
 141     $this->addClass('crm-search-form');
 142
 143     $tasks = $this->buildTaskList();
 144     $this->addTaskMenu($tasks);
 145   }
 146
 147   /**
 148    * Add any fields described in metadata to the form.
 149    *
 150    * The goal is to describe all fields in metadata and handle from metadata rather
 151    * than existing ad hoc handling.
 152    */
 153   public function addFormFieldsFromMetadata() {
 154     $this->addFormRule(['CRM_Core_Form_Search', 'formRule'], $this);
 155     $this->_action = CRM_Core_Action::ADVANCED;
 156     foreach ($this->getSearchFieldMetadata() as $entity => $fields) {
 157       foreach ($fields as $fieldName => $fieldSpec) {
 158         if ($fieldSpec['type'] === CRM_Utils_Type::T_DATE || $fieldSpec['type'] === (CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME)) {
 159           $this->addDatePickerRange($fieldName, $fieldSpec['title'], ($fieldSpec['type'] === (CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME)));
 160         }
 161         else {
 162           $this->addField($fieldName, ['entity' => $entity]);
 163         }
 164       }
 165     }
 166   }
 167
 168   /**
 169    * Global validation rules for the form.
 170    *
 171    * @param array $fields
 172    *   Posted values of the form.
 173    * @param array $files
 174    * @param object $form
 175    *
 176    * @return array
 177    *   list of errors to be posted back to the form
 178    */
 179   public static function formRule($fields, $files, $form) {
 180     $errors = [];
 181     if (!is_a($form, 'CRM_Core_Form_Search')) {
 182       // So this gets hit with a form object when doing an activity date search from
 183       // advanced search, but a NULL object when doing a pledge search.
 184       return $errors;
 185     }
 186     foreach ($form->getSearchFieldMetadata() as $entity => $spec) {
 187       foreach ($spec as $fieldName => $fieldSpec) {
 188         if ($fieldSpec['type'] === CRM_Utils_Type::T_DATE || $fieldSpec['type'] === (CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME)) {
 189           if (isset($fields[$fieldName . '_high']) && isset($fields[$fieldName . '_low']) && empty($fields[$fieldName . '_relative'])) {
 190             if (strtotime($fields[$fieldName . '_low']) > strtotime($fields[$fieldName . '_high'])) {
 191               $errors[$fieldName . '_low'] = ts('%1: Please check that your date range is in correct chronological order.', [1 => $fieldSpec['title']]);
 192             }
 193           }
 194         }
 195       }
 196     }
 197     return $errors;
 198   }
 199
 200   /**
 201    * Get the validation rule to apply to a function.
 202    *
 203    * Alphanumeric is designed to always be safe & for now we just return
 204    * that but in future we can use tighter rules for types like int, bool etc.
 205    *
 206    * @param string $entity
 207    * @param string $fieldName
 208    *
 209    * @return string
 210    */
 211   protected function getValidationTypeForField($entity, $fieldName) {
 212     switch ($this->getSearchFieldMetadata()[$entity][$fieldName]['type']) {
 213       case CRM_Utils_Type::T_BOOLEAN:
 214         return 'Boolean';
 215
 216       case CRM_Utils_Type::T_INT:
 217         return 'CommaSeparatedIntegers';
 218
 219       case CRM_Utils_Type::T_DATE:
 220       case CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME:
 221         return 'Timestamp';
 222
 223       default:
 224         return 'Alphanumeric';
 225     }
 226   }
 227
 228   /**
 229    * Get the defaults for the entity for any fields described in metadata.
 230    *
 231    * @param string $entity
 232    *
 233    * @return array
 234    */
 235   protected function getEntityDefaults($entity) {
 236     $defaults = [];
 237     foreach ($this->getSearchFieldMetadata()[$entity] as $fieldSpec) {
 238       if (empty($_POST[$fieldSpec['name']])) {
 239         $value = CRM_Utils_Request::retrieveValue($fieldSpec['name'], $this->getValidationTypeForField($entity, $fieldSpec['name']), FALSE, NULL, 'GET');
 240         if ($value !== FALSE) {
 241           $defaults[$fieldSpec['name']] = $value;
 242         }
 243         if ($fieldSpec['type'] === CRM_Utils_Type::T_DATE || ($fieldSpec['type'] === CRM_Utils_Type::T_DATE + CRM_Utils_Type::T_TIME)) {
 244           $low = CRM_Utils_Request::retrieveValue($fieldSpec['name'] . '_low', 'Timestamp', FALSE, NULL, 'GET');
 245           $high = CRM_Utils_Request::retrieveValue($fieldSpec['name'] . '_high', 'Timestamp', FALSE, NULL, 'GET');
 246           if ($low !== FALSE || $high !== FALSE) {
 247             $defaults[$fieldSpec['name'] . '_relative'] = 0;
 248             $defaults[$fieldSpec['name'] . '_low'] = $low ? date('Y-m-d H:i:s', strtotime($low)) : NULL;
 249             $defaults[$fieldSpec['name'] . '_high'] = $high ? date('Y-m-d H:i:s', strtotime($high)) : NULL;
 250           }
 251         }
 252       }
 253     }
 254     return $defaults;
 255   }
 256
 257   /**
 258    * Add checkboxes for each row plus a master checkbox.
 259    *
 260    * @param array $rows
 261    */
 262   public function addRowSelectors($rows) {
 263     $this->addElement('checkbox', 'toggleSelect', NULL, NULL, ['class' => 'select-rows']);
 264     if (!empty($rows)) {
 265       foreach ($rows as $row) {
 266         if (CRM_Utils_Array::value('checkbox', $row)) {
 267           $this->addElement('checkbox', $row['checkbox'], NULL, NULL, ['class' => 'select-row']);
 268         }
 269       }
 270     }
 271   }
 272
 273   /**
 274    * Add actions menu to search results form.
 275    *
 276    * @param array $tasks
 277    */
 278   public function addTaskMenu($tasks) {
 279     $taskMetaData = [];
 280     foreach ($tasks as $key => $task) {
 281       $taskMetaData[$key] = ['title' => $task];
 282     }
 283     parent::addTaskMenu($taskMetaData);
 284   }
 285
 286   /**
 287    * Add the sort-name field to the form.
 288    *
 289    * There is a setting to determine whether email is included in the search & we look this up to determine
 290    * which text to choose.
 291    *
 292    * Note that for translation purposes the full string works better than using 'prefix' hence we use override-able functions
 293    * to define the string.
 294    */
 295   protected function addSortNameField() {
 296     $this->addElement(
 297       'text',
 298       'sort_name',
 299       civicrm_api3('setting', 'getvalue', ['name' => 'includeEmailInName', 'group' => 'Search Preferences']) ? $this->getSortNameLabelWithEmail() : $this->getSortNameLabelWithOutEmail(),
 300       CRM_Core_DAO::getAttribute('CRM_Contact_DAO_Contact', 'sort_name')
 301     );
 302   }
 303
 304   /**
 305    * Get the label for the sortName field if email searching is on.
 306    *
 307    * (email searching is a setting under search preferences).
 308    *
 309    * @return string
 310    */
 311   protected function getSortNameLabelWithEmail() {
 312     return ts('Name or Email');
 313   }
 314
 315   /**
 316    * Get the label for the sortName field if email searching is off.
 317    *
 318    * (email searching is a setting under search preferences).
 319    *
 320    * @return string
 321    */
 322   protected function getSortNameLabelWithOutEmail() {
 323     return ts('Name');
 324   }
 325
 326   /**
 327    * Explicitly declare the form context for addField().
 328    */
 329   public function getDefaultContext() {
 330     return 'search';
 331   }
 332
 333   /**
 334    * Add generic fields that specify the contact.
 335    */
 336   protected function addContactSearchFields() {
 337     if (!$this->isFormInViewOrEditMode()) {
 338       return;
 339     }
 340     $this->addSortNameField();
 341
 342     $this->_group = CRM_Core_PseudoConstant::nestedGroup();
 343     if ($this->_group) {
 344       $this->add('select', 'group', $this->getGroupLabel(), $this->_group, FALSE,
 345         [
 346           'id' => 'group',
 347           'multiple' => 'multiple',
 348           'class' => 'crm-select2',
 349         ]
 350       );
 351     }
 352
 353     $contactTags = CRM_Core_BAO_Tag::getTags();
 354     if ($contactTags) {
 355       $this->add('select', 'contact_tags', $this->getTagLabel(), $contactTags, FALSE,
 356         [
 357           'id' => 'contact_tags',
 358           'multiple' => 'multiple',
 359           'class' => 'crm-select2',
 360         ]
 361       );
 362     }
 363     $this->addField('contact_type', ['entity' => 'Contact']);
 364
 365     if (CRM_Core_Permission::check('access deleted contacts') && Civi::settings()->get('contact_undelete')) {
 366       $this->addElement('checkbox', 'deleted_contacts', ts('Search in Trash') . '<br />' . ts('(deleted contacts)'));
 367     }
 368
 369   }
 370
 371   /**
 372    * we allow the controller to set force/reset externally, useful when we are being
 373    * driven by the wizard framework
 374    */
 375   protected function loadStandardSearchOptionsFromUrl() {
 376     $this->_reset = CRM_Utils_Request::retrieve('reset', 'Boolean');
 377     $this->_force = CRM_Utils_Request::retrieve('force', 'Boolean', $this, FALSE);
 378     $this->_limit = CRM_Utils_Request::retrieve('limit', 'Positive', $this);
 379     $this->_context = CRM_Utils_Request::retrieve('context', 'Alphanumeric', $this, FALSE, 'search');
 380     $this->_ssID = CRM_Utils_Request::retrieve('ssID', 'Positive', $this);
 381     $this->assign("context", $this->_context);
 382   }
 383
 384   /**
 385    * Get user submitted values.
 386    *
 387    * Get it from controller only if form has been submitted, else preProcess has set this
 388    */
 389   protected function loadFormValues() {
 390     if (!empty($_POST)  && !$this->controller->isModal()) {
 391       $this->_formValues = $this->controller->exportValues($this->_name);
 392     }
 393     else {
 394       $this->_formValues = $this->get('formValues');
 395     }
 396
 397     if (empty($this->_formValues)) {
 398       if (isset($this->_ssID)) {
 399         $this->_formValues = CRM_Contact_BAO_SavedSearch::getFormValues($this->_ssID);
 400       }
 401     }
 402   }
 403
 404 }