CRM/Core/Selector/Controller.php

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