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
 160     $entityIds = [];
 161     if ($searchFormValues['radio_ts'] == 'ts_sel') {
 162       foreach ($searchFormValues as $name => $value) {
 163         if (substr($name, 0, CRM_Core_Form::CB_PREFIX_LEN) == CRM_Core_Form::CB_PREFIX) {
 164           $entityIds[] = substr($name, CRM_Core_Form::CB_PREFIX_LEN);
 165         }
 166       }
 167     }
 168     else {
 169       $queryParams = $form->get('queryParams');
 170       $sortOrder = NULL;
 171       if ($form->get(CRM_Utils_Sort::SORT_ORDER)) {
 172         $sortOrder = $form->get(CRM_Utils_Sort::SORT_ORDER);
 173       }
 174
 175       $query = new CRM_Contact_BAO_Query($queryParams, NULL, NULL, FALSE, FALSE, $form->getQueryMode());
 176       $query->_distinctComponentClause = $form->getDistinctComponentClause();
 177       $query->_groupByComponentClause = $form->getGroupByComponentClause();
 178       $result = $query->searchQuery(0, 0, $sortOrder);
 179       $selector = $form->getEntityAliasField();
 180       while ($result->fetch()) {
 181         $entityIds[] = $result->$selector;
 182       }
 183     }
 184
 185     if (!empty($entityIds)) {
 186       $form->_componentClause = ' ' . $form->getTableName() . '.id IN ( ' . implode(',', $entityIds) . ' ) ';
 187       $form->assign('totalSelected' . ucfirst($form::$entityShortname) . 's', count($entityIds));
 188     }
 189
 190     $form->_entityIds = $form->_componentIds = $entityIds;
 191
 192     // Some functions (eg. PDF letter tokens) rely on Ids being in specific fields rather than the generic $form->_entityIds
 193     // So we set that specific field here (eg. for cases $form->_caseIds = $form->_entityIds).
 194     // FIXME: This is really to handle legacy code that should probably be updated to use $form->_entityIds
 195     $entitySpecificIdsName = '_' . $form::$entityShortname . 'Ids';
 196     $form->$entitySpecificIdsName = $form->_entityIds;
 197     $form->setNextUrl($form::$entityShortname);
 198
 199   }
 200
 201   /**
 202    * Given the entity id, compute the contact id since its used for things like send email
 203    * For example, for cases we need to override this function as the table name is civicrm_case_contact
 204    */
 205   public function setContactIDs() {
 206     $this->_contactIds = CRM_Core_DAO::getContactIDsFromComponent($this->_entityIds,
 207       $this->getTableName()
 208     );
 209   }
 210
 211   /**
 212    * Add buttons to the form.
 213    *
 214    * @param string $title
 215    *   Title of the main button.
 216    * @param string $nextType
 217    *   Button type for the form after processing.
 218    * @param string $backType
 219    * @param bool $submitOnce
 220    */
 221   public function addDefaultButtons($title, $nextType = 'next', $backType = 'back', $submitOnce = FALSE) {
 222     $this->addButtons([
 223       [
 224         'type' => $nextType,
 225         'name' => $title,
 226         'isDefault' => TRUE,
 227       ],
 228       [
 229         'type' => $backType,
 230         'name' => ts('Cancel'),
 231       ],
 232     ]);
 233   }
 234
 235   /**
 236    * Get the query mode (eg. CRM_Core_BAO_Query::MODE_CASE)
 237    * Should be overridden by child classes in most cases
 238    *
 239    * @return int
 240    */
 241   public function getQueryMode() {
 242     return $this->queryMode ?: CRM_Contact_BAO_Query::MODE_CONTACTS;
 243   }
 244
 245   /**
 246    * Given the component id, compute the contact id
 247    * since it's used for things like send email.
 248    *
 249    * @todo At the moment this duplicates a similar function in CRM_Core_DAO
 250    * because right now only the case component is using this. Since the
 251    * default $orderBy is '' which is what the original does, others should be
 252    * easily convertable as NFC.
 253    * @todo The passed in variables should be class member variables. Shouldn't
 254    * need to have passed in vars.
 255    *
 256    * @param $componentIDs
 257    * @param string $tableName
 258    * @param string $idField
 259    *
 260    * @return array
 261    */
 262   public function getContactIDsFromComponent($componentIDs, $tableName, $idField = 'id') {
 263     $contactIDs = [];
 264
 265     if (empty($componentIDs)) {
 266       return $contactIDs;
 267     }
 268
 269     $orderBy = $this->orderBy();
 270
 271     $IDs = implode(',', $componentIDs);
 272     $query = "
 273 SELECT contact_id
 274   FROM $tableName
 275  WHERE $idField IN ( $IDs ) $orderBy
 276 ";
 277
 278     $dao = CRM_Core_DAO::executeQuery($query);
 279     while ($dao->fetch()) {
 280       $contactIDs[] = $dao->contact_id;
 281     }
 282     return $contactIDs;
 283   }
 284
 285   /**
 286    * Default ordering for getContactIDsFromComponent. Subclasses can override.
 287    *
 288    * @return string
 289    *   SQL fragment. Either return '' or a valid order clause including the
 290    *   words "ORDER BY", e.g. "ORDER BY `{$this->idField}`"
 291    */
 292   public function orderBy() {
 293     return '';
 294   }
 295
 296   /**
 297    * Get the submitted values for the form.
 298    *
 299    * @return array
 300    */
 301   public function getSearchFormValues() {
 302     if ($this->_action === CRM_Core_Action::ADVANCED) {
 303       return $this->controller->exportValues('Advanced');
 304     }
 305     if ($this->_action === CRM_Core_Action::PROFILE) {
 306       return $this->controller->exportValues('Builder');
 307     }
 308     if ($this->_action == CRM_Core_Action::COPY) {
 309       return $this->controller->exportValues('Custom');
 310     }
 311     if ($this->get('entity') !== 'Contact') {
 312       return $this->controller->exportValues('Search');
 313     }
 314     return $this->controller->exportValues('Basic');
 315   }
 316
 317   /**
 318    * Get the name of the table for the relevant entity.
 319    *
 320    * @return string
 321    */
 322   public function getTableName() {
 323     CRM_Core_Error::deprecatedFunctionWarning('function should be overridden');
 324     return $this::$tableName;
 325   }
 326
 327   /**
 328    * Get the clause for grouping by the component.
 329    *
 330    * @return string
 331    */
 332   public function getDistinctComponentClause() {
 333     return " ( " . $this->getTableName() . ".id )";
 334   }
 335
 336   /**
 337    * Get the group by clause for the component.
 338    *
 339    * @return string
 340    */
 341   public function getGroupByComponentClause() {
 342     return " GROUP BY " . $this->getTableName() . ".id ";
 343   }
 344
 345   /**
 346    * Get the group by clause for the component.
 347    *
 348    * @return string
 349    */
 350   public function getEntityAliasField() {
 351     CRM_Core_Error::deprecatedFunctionWarning('function should be overridden');
 352     return $this::$entityShortname . '_id';
 353   }
 354
 355   /**
 356    * List available tokens for this form.
 357    *
 358    * @return array
 359    */
 360   public function listTokens() {
 361     $tokenProcessor = new TokenProcessor(Civi::dispatcher(), ['schema' => $this->getTokenSchema()]);
 362     return $tokenProcessor->listTokens();
 363   }
 364
 365   /**
 366    * Get the token processor schema required to list any tokens for this task.
 367    *
 368    * @return array
 369    */
 370   protected function getTokenSchema(): array {
 371     return ['contactId'];
 372   }
 373
 374   /**
 375    * Get the rows from the results.
 376    *
 377    * @return array
 378    */
 379   protected function getRows(): array {
 380     $rows = [];
 381     foreach ($this->getContactIDs() as $contactID) {
 382       $rows[] = ['contact_id' => $contactID, 'schema' => ['contactId' => $contactID]];
 383     }
 384     return $rows;
 385   }
 386
 387   /**
 388    * Get the relevant contact IDs.
 389    *
 390    * @return array
 391    */
 392   protected function getContactIDs(): array {
 393     return $this->_contactIds ?? [];
 394   }
 395
 396 }