CRM/Core/Selector/Controller.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  *
  30  * This class is a generic class to be used when we want to display
  31  * a list of rows along with a set of associated actions
  32  *
  33  * Centralizing this code enables us to write a generic lister and enables
  34  * us to automate the export process. To use this class, the object has to
  35  * implement the Selector/Api.interface.php class
  36  *
  37  * @package CRM
  38  * @copyright CiviCRM LLC (c) 2004-2019
  39  * $Id$
  40  *
  41  */
  42 class CRM_Core_Selector_Controller {
  43
  44   /**
  45    * Constants to determine if we should store
  46    * the output in the session or template
  47    * @var int
  48    */
  49   // move the values from the session to the template
  50   const SESSION = 1, TEMPLATE = 2,
  51     TRANSFER = 4, EXPORT = 8, SCREEN = 16, PDF = 32;
  52
  53   /**
  54    * A CRM Object that implements CRM_Core_Selector_API.
  55    * @var object
  56    */
  57   protected $_object;
  58
  59   /**
  60    * @var CRM_Utils_Sort
  61    */
  62   protected $_sort;
  63
  64   /**
  65    * The current column to sort on
  66    * @var int
  67    */
  68   protected $_sortID;
  69
  70   /**
  71    * The sortOrder array
  72    * @var array
  73    */
  74   protected $_sortOrder;
  75
  76   /**
  77    * @var CRM_Utils_Pager
  78    */
  79   protected $_pager;
  80
  81   /**
  82    * The pageID
  83    * @var int
  84    */
  85   protected $_pageID;
  86
  87   /**
  88    * Offset
  89    * @var int
  90    */
  91   protected $_pagerOffset;
  92
  93   /**
  94    * Number of rows to return
  95    * @var int
  96    */
  97   protected $_pagerRowCount;
  98
  99   /**
 100    * Total number of rows
 101    * @var int
 102    */
 103   protected $_total;
 104
 105   /**
 106    * The objectAction for the WebObject
 107    * @var int
 108    */
 109   protected $_action;
 110
 111   /**
 112    * This caches the content for the display system
 113    *
 114    * @var string
 115    */
 116   protected $_content;
 117
 118   /**
 119    * Is this object being embedded in another object. If
 120    * so the display routine needs to not do any work. (The
 121    * parent object takes care of the display)
 122    *
 123    * @var bool
 124    */
 125   protected $_embedded = FALSE;
 126
 127   /**
 128    * Are we in print mode? if so we need to modify the display
 129    * functionality to do a minimal display :)
 130    *
 131    * @var bool
 132    */
 133   protected $_print = FALSE;
 134
 135   /**
 136    * The storage object (typically a form or a page)
 137    *
 138    * @var Object
 139    */
 140   protected $_store;
 141
 142   /**
 143    * Output target, session, template or both?
 144    *
 145    * @var int
 146    */
 147   protected $_output;
 148
 149   /**
 150    * Prefif for the selector variables
 151    *
 152    * @var int
 153    */
 154   protected $_prefix;
 155
 156   /**
 157    * Cache the smarty template for efficiency reasons
 158    *
 159    * @var CRM_Core_Smarty
 160    */
 161   public static $_template;
 162
 163   /**
 164    * Array of properties that the controller dumps into the output object
 165    *
 166    * @var array
 167    */
 168   public static $_properties = ['columnHeaders', 'rows', 'rowsEmpty'];
 169
 170   /**
 171    * Should we compute actions dynamically (since they are quite verbose)
 172    *
 173    * @var bool
 174    */
 175   protected $_dynamicAction = FALSE;
 176
 177   /**
 178    * Class constructor.
 179    *
 180    * @param CRM_Core_Selector_API $object
 181    *   An object that implements the selector API.
 182    * @param int $pageID
 183    *   Default pageID.
 184    * @param int $sortID
 185    *   Default sortID.
 186    * @param int $action
 187    *   The actions to potentially support.
 188    * @param CRM_Core_Page|CRM_Core_Form $store place in session to store some values
 189    * @param int $output
 190    *   What do we so with the output, session/template//both.
 191    *
 192    * @param null $prefix
 193    * @param null $case
 194    *
 195    * @return \CRM_Core_Selector_Controller
 196    */
 197   public function __construct($object, $pageID, $sortID, $action, $store = NULL, $output = self::TEMPLATE, $prefix = NULL, $case = NULL) {
 198
 199     $this->_object = $object;
 200     $this->_pageID = $pageID ? $pageID : 1;
 201     $this->_sortID = $sortID ? $sortID : NULL;
 202     $this->_action = $action;
 203     $this->_store = $store;
 204     $this->_output = $output;
 205     $this->_prefix = $prefix;
 206     $this->_case = $case;
 207
 208     // fix sortID
 209     if ($this->_sortID && strpos($this->_sortID, '_') === FALSE) {
 210       $this->_sortID .= '_u';
 211     }
 212
 213     $params = [
 214       'pageID' => $this->_pageID,
 215     ];
 216
 217     // let the constructor initialize this, should happen only once
 218     if (!isset(self::$_template)) {
 219       self::$_template = CRM_Core_Smarty::singleton();
 220     }
 221
 222     $this->_sortOrder = &$this->_object->getSortOrder($action);
 223     $this->_sort = new CRM_Utils_Sort($this->_sortOrder, $this->_sortID);
 224
 225     /*
 226      * if we are in transfer mode, do not goto database, use the
 227      * session values instead
 228      */
 229
 230     if ($output == self::TRANSFER) {
 231       $params['total'] = $this->_store->get($this->_prefix . 'rowCount');
 232     }
 233     else {
 234       $params['total'] = $this->_object->getTotalCount($action, $this->_case);
 235     }
 236
 237     $this->_total = $params['total'];
 238     $this->_object->getPagerParams($action, $params);
 239
 240     /*
 241      * Set the default values of RowsPerPage
 242      */
 243
 244     $storeRowCount = $store->get($this->_prefix . CRM_Utils_Pager::PAGE_ROWCOUNT);
 245     if ($storeRowCount) {
 246       $params['rowCount'] = $storeRowCount;
 247     }
 248     elseif (!isset($params['rowCount'])) {
 249       $params['rowCount'] = CRM_Utils_Pager::ROWCOUNT;
 250     }
 251
 252     $this->_pager = new CRM_Utils_Pager($params);
 253     list($this->_pagerOffset, $this->_pagerRowCount) = $this->_pager->getOffsetAndRowCount();
 254   }
 255
 256   /**
 257    * Have the GET vars changed, i.e. pageId or sortId that forces us to recompute the search values
 258    *
 259    * @param int $reset
 260    *   Are we being reset.
 261    *
 262    * @return bool
 263    *   if the GET params are different from the session params
 264    */
 265   public function hasChanged($reset) {
 266
 267     /**
 268      * if we are in reset state, i.e the store is cleaned out, we return false
 269      * we also return if we dont have a record of the sort id or page id
 270      */
 271     if ($reset ||
 272       $this->_store->get($this->_prefix . CRM_Utils_Pager::PAGE_ID) == NULL ||
 273       $this->_store->get($this->_prefix . CRM_Utils_Sort::SORT_ID) == NULL
 274     ) {
 275       return FALSE;
 276     }
 277
 278     if ($this->_store->get($this->_prefix . CRM_Utils_Pager::PAGE_ID) != $this->_pager->getCurrentPageID() ||
 279       $this->_store->get($this->_prefix . CRM_Utils_Sort::SORT_ID) != $this->_sort->getCurrentSortID() ||
 280       $this->_store->get($this->_prefix . CRM_Utils_Sort::SORT_DIRECTION) != $this->_sort->getCurrentSortDirection()
 281     ) {
 282       return TRUE;
 283     }
 284     return FALSE;
 285   }
 286
 287   /**
 288    * Heart of the Controller. This is where all the action takes place
 289    *
 290    *   - The rows are fetched and stored depending on the type of output needed
 291    *
 292    *   - For export/printing all rows are selected.
 293    *
 294    *   - for displaying on screen paging parameters are used to display the
 295    *     required rows.
 296    *
 297    *   - also depending on output type of session or template rows are appropriately stored in session
 298    *     or template variables are updated.
 299    *
 300    *
 301    * @return void
 302    */
 303   public function run() {
 304
 305     // get the column headers
 306     $columnHeaders = &$this->_object->getColumnHeaders($this->_action, $this->_output);
 307
 308     $contextArray = explode('_', get_class($this->_object));
 309
 310     $contextName = strtolower($contextArray[1]);
 311
 312     // fix contribute and member
 313     if ($contextName == 'contribute') {
 314       $contextName = 'contribution';
 315     }
 316     elseif ($contextName == 'member') {
 317       $contextName = 'membership';
 318     }
 319
 320     // we need to get the rows if we are exporting or printing them
 321     if ($this->_output == self::EXPORT || $this->_output == self::SCREEN) {
 322       // get rows (without paging criteria)
 323       $rows = self::getRows($this);
 324       CRM_Utils_Hook::searchColumns($contextName, $columnHeaders, $rows, $this);
 325       if ($this->_output == self::EXPORT) {
 326         // export the rows.
 327         CRM_Core_Report_Excel::writeCSVFile($this->_object->getExportFileName(),
 328           $columnHeaders,
 329           $rows
 330         );
 331         CRM_Utils_System::civiExit();
 332       }
 333       else {
 334         // assign to template and display them.
 335         self::$_template->assign_by_ref('rows', $rows);
 336         self::$_template->assign_by_ref('columnHeaders', $columnHeaders);
 337       }
 338     }
 339     else {
 340       // output requires paging/sorting capability
 341       $rows = self::getRows($this);
 342       CRM_Utils_Hook::searchColumns($contextName, $columnHeaders, $rows, $this);
 343       $reorderedHeaders = [];
 344       $noWeightHeaders = [];
 345       foreach ($columnHeaders as $key => $columnHeader) {
 346         // So far only contribution selector sets weight, so just use key if not.
 347         // Extension writers will need to fix other getColumnHeaders (or add a wrapper)
 348         // to extend.
 349         if (isset($columnHeader['weight'])) {
 350           $reorderedHeaders[$columnHeader['weight']] = $columnHeader;
 351         }
 352         else {
 353           $noWeightHeaders[$key] = $columnHeader;
 354         }
 355       }
 356       ksort($reorderedHeaders);
 357       // Merge headers not containing weight to ordered headers
 358       $finalColumnHeaders = array_merge($reorderedHeaders, $noWeightHeaders);
 359
 360       $rowsEmpty = count($rows) ? FALSE : TRUE;
 361       $qill = $this->getQill();
 362       $summary = $this->getSummary();
 363       // if we need to store in session, lets update session
 364       if ($this->_output & self::SESSION) {
 365         $this->_store->set("{$this->_prefix}columnHeaders", $finalColumnHeaders);
 366         if ($this->_dynamicAction) {
 367           $this->_object->removeActions($rows);
 368         }
 369         $this->_store->set("{$this->_prefix}rows", $rows);
 370         $this->_store->set("{$this->_prefix}rowCount", $this->_total);
 371         $this->_store->set("{$this->_prefix}rowsEmpty", $rowsEmpty);
 372         $this->_store->set("{$this->_prefix}qill", $qill);
 373         $this->_store->set("{$this->_prefix}summary", $summary);
 374       }
 375       else {
 376         self::$_template->assign_by_ref("{$this->_prefix}pager", $this->_pager);
 377         self::$_template->assign_by_ref("{$this->_prefix}sort", $this->_sort);
 378
 379         self::$_template->assign_by_ref("{$this->_prefix}columnHeaders", $finalColumnHeaders);
 380         self::$_template->assign_by_ref("{$this->_prefix}rows", $rows);
 381         self::$_template->assign("{$this->_prefix}rowsEmpty", $rowsEmpty);
 382         self::$_template->assign("{$this->_prefix}qill", $qill);
 383         self::$_template->assign("{$this->_prefix}summary", $summary);
 384       }
 385
 386       // always store the current pageID and sortID
 387       $this->_store->set($this->_prefix . CRM_Utils_Pager::PAGE_ID,
 388         $this->_pager->getCurrentPageID()
 389       );
 390       $this->_store->set($this->_prefix . CRM_Utils_Sort::SORT_ID,
 391         $this->_sort->getCurrentSortID()
 392       );
 393       $this->_store->set($this->_prefix . CRM_Utils_Sort::SORT_DIRECTION,
 394         $this->_sort->getCurrentSortDirection()
 395       );
 396       $this->_store->set($this->_prefix . CRM_Utils_Sort::SORT_ORDER,
 397         $this->_sort->orderBy()
 398       );
 399       $this->_store->set($this->_prefix . CRM_Utils_Pager::PAGE_ROWCOUNT,
 400         $this->_pager->_perPage
 401       );
 402     }
 403   }
 404
 405   /**
 406    * Retrieve rows.
 407    *
 408    * @param CRM_Core_Form $form
 409    *
 410    * @return array
 411    *   Array of rows
 412    */
 413   public function getRows($form) {
 414     if ($form->_output == self::EXPORT || $form->_output == self::SCREEN) {
 415       //get rows (without paging criteria)
 416       return $form->_object->getRows($form->_action, 0, 0, $form->_sort, $form->_output);
 417     }
 418     else {
 419       return $form->_object->getRows($form->_action, $form->_pagerOffset, $form->_pagerRowCount,
 420         $form->_sort, $form->_output, $form->_case
 421       );
 422     }
 423   }
 424
 425   /**
 426    * Default function for qill, if needed to be implemented, we
 427    * expect the subclass to do it
 428    *
 429    * @return string
 430    *   the status message
 431    */
 432   public function getQill() {
 433     return $this->_object->getQill();
 434   }
 435
 436   /**
 437    * @return mixed
 438    */
 439   public function getSummary() {
 440     return $this->_object->getSummary();
 441   }
 442
 443   /**
 444    * Getter for pager.
 445    *
 446    * @return CRM_Utils_Pager
 447    */
 448   public function getPager() {
 449     return $this->_pager;
 450   }
 451
 452   /**
 453    * Getter for sort.
 454    *
 455    * @return CRM_Utils_Sort
 456    */
 457   public function getSort() {
 458     return $this->_sort;
 459   }
 460
 461   /**
 462    * Move the variables from the session to the template.
 463    *
 464    * @return void
 465    */
 466   public function moveFromSessionToTemplate() {
 467     self::$_template->assign_by_ref("{$this->_prefix}pager", $this->_pager);
 468
 469     $rows = $this->_store->get("{$this->_prefix}rows");
 470
 471     if ($rows) {
 472       if ($this->_dynamicAction) {
 473         $this->_object->addActions($rows);
 474       }
 475
 476       self::$_template->assign("{$this->_prefix}aToZ",
 477         $this->_store->get("{$this->_prefix}AToZBar")
 478       );
 479     }
 480
 481     self::$_template->assign_by_ref("{$this->_prefix}sort", $this->_sort);
 482     self::$_template->assign("{$this->_prefix}columnHeaders", $this->_store->get("{$this->_prefix}columnHeaders"));
 483     self::$_template->assign("{$this->_prefix}rows", $rows);
 484     self::$_template->assign("{$this->_prefix}rowsEmpty", $this->_store->get("{$this->_prefix}rowsEmpty"));
 485     self::$_template->assign("{$this->_prefix}qill", $this->_store->get("{$this->_prefix}qill"));
 486     self::$_template->assign("{$this->_prefix}summary", $this->_store->get("{$this->_prefix}summary"));
 487
 488     if ($this->_embedded) {
 489       return;
 490     }
 491
 492     self::$_template->assign('tplFile', $this->_object->getHookedTemplateFileName());
 493     if ($this->_print) {
 494       $content = self::$_template->fetch('CRM/common/print.tpl');
 495     }
 496     else {
 497       $config = CRM_Core_Config::singleton();
 498       $content = self::$_template->fetch('CRM/common/' . strtolower($config->userFramework) . '.tpl');
 499     }
 500     echo CRM_Utils_System::theme($content, $this->_print);
 501   }
 502
 503   /**
 504    * Setter for embedded.
 505    *
 506    * @param bool $embedded
 507    *
 508    * @return void
 509    */
 510   public function setEmbedded($embedded) {
 511     $this->_embedded = $embedded;
 512   }
 513
 514   /**
 515    * Getter for embedded.
 516    *
 517    * @return bool
 518    *   return the embedded value
 519    */
 520   public function getEmbedded() {
 521     return $this->_embedded;
 522   }
 523
 524   /**
 525    * Setter for print.
 526    *
 527    * @param bool $print
 528    *
 529    * @return void
 530    */
 531   public function setPrint($print) {
 532     $this->_print = $print;
 533   }
 534
 535   /**
 536    * Getter for print.
 537    *
 538    * @return bool
 539    *   return the print value
 540    */
 541   public function getPrint() {
 542     return $this->_print;
 543   }
 544
 545   /**
 546    * @param $value
 547    */
 548   public function setDynamicAction($value) {
 549     $this->_dynamicAction = $value;
 550   }
 551
 552   /**
 553    * @return bool
 554    */
 555   public function getDynamicAction() {
 556     return $this->_dynamicAction;
 557   }
 558
 559 }