CRM/Core/Form/Task.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 use Civi\Token\TokenProcessor;
  13
  14 /**
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  */
  18
  19 /**
  20  * This is a shared parent class for form task actions.
  21  */
  22 abstract class CRM_Core_Form_Task extends CRM_Core_Form {
  23
  24   /**
  25    * The task being performed
  26    *
  27    * @var int
  28    */
  29   protected $_task;
  30
  31   /**
  32    * The additional clause that we restrict the search with
  33    *
  34    * @var string
  35    */
  36   protected $_componentClause = NULL;
  37
  38   /**
  39    * The array that holds all the component ids
  40    *
  41    * @var array
  42    */
  43   protected $_componentIds;
  44
  45   /**
  46    * @var int
  47    */
  48   protected $queryMode;
  49
  50   /**
  51    * The array that holds all the case ids
  52    *
  53    * @var array
  54    */
  55   public $_entityIds;
  56
  57   /**
  58    * The array that holds all the contact ids
  59    *
  60    * @var array
  61    */
  62   public $_contactIds;
  63
  64   /**
  65    * Must be set to entity table name (eg. civicrm_participant) by child class
  66    *
  67    * @var string
  68    */
  69   public static $tableName = NULL;
  70
  71   /**
  72    * Must be set to entity shortname (eg. event)
  73    *
  74    * @var string
  75    */
  76   public static $entityShortname = NULL;
  77
  78
  79   /**
  80    * Rows to act on.
  81    *
  82    * e.g
  83    *  [
  84    *    ['contact_id' => 4, 'participant_id' => 6, 'schema' => ['contactId' => 5, 'participantId' => 6],
  85    *  ]
  86    * @var array
  87    */
  88   protected $rows = [];
  89
  90   /**
  91    * Set where the browser should be directed to next.
  92    *
  93    * @param string $pathPart
  94    *
  95    * @throws \CRM_Core_Exception
  96    */
  97   public function setNextUrl(string $pathPart) {
  98     //set the context for redirection for any task actions
  99     $qfKey = CRM_Utils_Request::retrieve('qfKey', 'String', $this);
 100     $urlParams = 'force=1';
 101     if (CRM_Utils_Rule::qfKey($qfKey)) {
 102       $urlParams .= "&qfKey=$qfKey";
 103     }
 104
 105     $session = CRM_Core_Session::singleton();
 106     $searchFormName = strtolower($this->get('searchFormName') ?? '');
 107     if ($searchFormName === 'search') {
 108       $session->replaceUserContext(CRM_Utils_System::url('civicrm/' . $pathPart . '/search', $urlParams));
 109     }
 110     else {
 111       $session->replaceUserContext(CRM_Utils_System::url("civicrm/contact/search/$searchFormName",
 112         $urlParams
 113       ));
 114     }
 115   }
 116
 117   /**
 118    * Get the ids the user has selected or FALSE if selection has not been used.
 119    *
 120    * @param array $values
 121    *
 122    * @return array|bool
 123    */
 124   public function getSelectedIDs(array $values) {
 125     if ($values['radio_ts'] === 'ts_sel') {
 126       $ids = [];
 127       foreach ($values as $name => $value) {
 128         if (substr($name, 0, CRM_Core_Form::CB_PREFIX_LEN) == CRM_Core_Form::CB_PREFIX) {
 129           $ids[] = substr($name, CRM_Core_Form::CB_PREFIX_LEN);
 130         }
 131       }
 132       return $ids;
 133     }
 134     return FALSE;
 135   }
 136
 137   /**
 138    * Build all the data structures needed to build the form.
 139    *
 140    * @throws \CRM_Core_Exception
 141    */
 142   public function preProcess() {
 143     self::preProcessCommon($this);
 144   }
 145
 146   /**
 147    * Common pre-processing function.
 148    *
 149    * @param CRM_Core_Form_Task $form
 150    *
 151    * @throws \CRM_Core_Exception
 152    */
 153   public static function preProcessCommon(&$form) {
 154     $form->_entityIds = [];
 155
 156     $searchFormValues = $form->getSearchFormValues();
 157
 158     $form->_task = $searchFormValues['task'];
 159     $isSelectedContacts = ($searchFormValues['radio_ts'] ?? NULL) === 'ts_sel';
 160     $form->assign('isSelectedContacts', $isSelectedContacts);
 161     $entityIds = [];
 162     if ($isSelectedContacts) {
 163       foreach ($searchFormValues as $name => $value) {
 164         if (substr($name, 0, CRM_Core_Form::CB_PREFIX_LEN) == CRM_Core_Form::CB_PREFIX) {
 165           $entityIds[] = substr($name, CRM_Core_Form::CB_PREFIX_LEN);
 166         }
 167       }
 168     }
 169     else {
 170       $queryParams = $form->get('queryParams');
 171       $sortOrder = NULL;
 172       if ($form->get(CRM_Utils_Sort::SORT_ORDER)) {
 173         $sortOrder = $form->get(CRM_Utils_Sort::SORT_ORDER);
 174       }
 175
 176       $query = new CRM_Contact_BAO_Query($queryParams, NULL, NULL, FALSE, FALSE, $form->getQueryMode());
 177       $query->_distinctComponentClause = $form->getDistinctComponentClause();
 178       $query->_groupByComponentClause = $form->getGroupByComponentClause();
 179       $result = $query->searchQuery(0, 0, $sortOrder);
 180       $selector = $form->getEntityAliasField();
 181       while ($result->fetch()) {
 182         $entityIds[] = $result->$selector;
 183       }
 184     }
 185
 186     if (!empty($entityIds)) {
 187       $form->_componentClause = ' ' . $form->getTableName() . '.id IN ( ' . implode(',', $entityIds) . ' ) ';
 188       $form->assign('totalSelected' . ucfirst($form::$entityShortname) . 's', count($entityIds));
 189     }
 190
 191     $form->_entityIds = $form->_componentIds = $entityIds;
 192
 193     // Some functions (eg. PDF letter tokens) rely on Ids being in specific fields rather than the generic $form->_entityIds
 194     // So we set that specific field here (eg. for cases $form->_caseIds = $form->_entityIds).
 195     // FIXME: This is really to handle legacy code that should probably be updated to use $form->_entityIds
 196     $entitySpecificIdsName = '_' . $form::$entityShortname . 'Ids';
 197     $form->$entitySpecificIdsName = $form->_entityIds;
 198     $form->setNextUrl($form::$entityShortname);
 199
 200   }
 201
 202   /**
 203    * Given the entity id, compute the contact id since its used for things like send email
 204    * For example, for cases we need to override this function as the table name is civicrm_case_contact
 205    */
 206   public function setContactIDs() {
 207     $this->_contactIds = CRM_Core_DAO::getContactIDsFromComponent($this->_entityIds,
 208       $this->getTableName()
 209     );
 210   }
 211
 212   /**
 213    * Add buttons to the form.
 214    *
 215    * @param string $title
 216    *   Title of the main button.
 217    * @param string $nextType
 218    *   Button type for the form after processing.
 219    * @param string $backType
 220    * @param bool $submitOnce
 221    */
 222   public function addDefaultButtons($title, $nextType = 'next', $backType = 'back', $submitOnce = FALSE) {
 223     $this->addButtons([
 224       [
 225         'type' => $nextType,
 226         'name' => $title,
 227         'isDefault' => TRUE,
 228       ],
 229       [
 230         'type' => $backType,
 231         'name' => ts('Cancel'),
 232       ],
 233     ]);
 234   }
 235
 236   /**
 237    * Get the query mode (eg. CRM_Core_BAO_Query::MODE_CASE)
 238    * Should be overridden by child classes in most cases
 239    *
 240    * @return int
 241    */
 242   public function getQueryMode() {
 243     return $this->queryMode ?: CRM_Contact_BAO_Query::MODE_CONTACTS;
 244   }
 245
 246   /**
 247    * Given the component id, compute the contact id
 248    * since it's used for things like send email.
 249    *
 250    * @todo At the moment this duplicates a similar function in CRM_Core_DAO
 251    * because right now only the case component is using this. Since the
 252    * default $orderBy is '' which is what the original does, others should be
 253    * easily convertable as NFC.
 254    * @todo The passed in variables should be class member variables. Shouldn't
 255    * need to have passed in vars.
 256    *
 257    * @param $componentIDs
 258    * @param string $tableName
 259    * @param string $idField
 260    *
 261    * @return array
 262    */
 263   public function getContactIDsFromComponent($componentIDs, $tableName, $idField = 'id') {
 264     $contactIDs = [];
 265
 266     if (empty($componentIDs)) {
 267       return $contactIDs;
 268     }
 269
 270     $orderBy = $this->orderBy();
 271
 272     $IDs = implode(',', $componentIDs);
 273     $query = "
 274 SELECT contact_id
 275   FROM $tableName
 276  WHERE $idField IN ( $IDs ) $orderBy
 277 ";
 278
 279     $dao = CRM_Core_DAO::executeQuery($query);
 280     while ($dao->fetch()) {
 281       $contactIDs[] = $dao->contact_id;
 282     }
 283     return $contactIDs;
 284   }
 285
 286   /**
 287    * Default ordering for getContactIDsFromComponent. Subclasses can override.
 288    *
 289    * @return string
 290    *   SQL fragment. Either return '' or a valid order clause including the
 291    *   words "ORDER BY", e.g. "ORDER BY `{$this->idField}`"
 292    */
 293   public function orderBy() {
 294     return '';
 295   }
 296
 297   /**
 298    * Get the submitted values for the form.
 299    *
 300    * @return array
 301    */
 302   public function getSearchFormValues() {
 303     if ($this->_action === CRM_Core_Action::ADVANCED) {
 304       return $this->controller->exportValues('Advanced');
 305     }
 306     if ($this->_action === CRM_Core_Action::PROFILE) {
 307       return $this->controller->exportValues('Builder');
 308     }
 309     if ($this->_action == CRM_Core_Action::COPY) {
 310       return $this->controller->exportValues('Custom');
 311     }
 312     if ($this->get('entity') !== 'Contact') {
 313       return $this->controller->exportValues('Search');
 314     }
 315     return $this->controller->exportValues('Basic');
 316   }
 317
 318   /**
 319    * Get the name of the table for the relevant entity.
 320    *
 321    * @return string
 322    */
 323   public function getTableName() {
 324     CRM_Core_Error::deprecatedFunctionWarning('function should be overridden');
 325     return $this::$tableName;
 326   }
 327
 328   /**
 329    * Get the clause for grouping by the component.
 330    *
 331    * @return string
 332    */
 333   public function getDistinctComponentClause() {
 334     return " ( " . $this->getTableName() . ".id )";
 335   }
 336
 337   /**
 338    * Get the group by clause for the component.
 339    *
 340    * @return string
 341    */
 342   public function getGroupByComponentClause() {
 343     return " GROUP BY " . $this->getTableName() . ".id ";
 344   }
 345
 346   /**
 347    * Get the group by clause for the component.
 348    *
 349    * @return string
 350    */
 351   public function getEntityAliasField() {
 352     CRM_Core_Error::deprecatedFunctionWarning('function should be overridden');
 353     return $this::$entityShortname . '_id';
 354   }
 355
 356   /**
 357    * List available tokens for this form.
 358    *
 359    * @return array
 360    */
 361   public function listTokens() {
 362     $tokenProcessor = new TokenProcessor(Civi::dispatcher(), ['schema' => $this->getTokenSchema()]);
 363     return $tokenProcessor->listTokens();
 364   }
 365
 366   /**
 367    * Get the token processor schema required to list any tokens for this task.
 368    *
 369    * @return array
 370    */
 371   protected function getTokenSchema(): array {
 372     return ['contactId'];
 373   }
 374
 375   /**
 376    * Get the rows from the results.
 377    *
 378    * @return array
 379    */
 380   protected function getRows(): array {
 381     $rows = [];
 382     foreach ($this->getContactIDs() as $contactID) {
 383       $rows[] = ['contact_id' => $contactID, 'schema' => ['contactId' => $contactID]];
 384     }
 385     return $rows;
 386   }
 387
 388   /**
 389    * Get the relevant contact IDs.
 390    *
 391    * @return array
 392    */
 393   protected function getContactIDs(): array {
 394     return $this->_contactIds ?? [];
 395   }
 396
 397 }