CRM/Core/State.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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  * The basic state element. Each state element is linked to a form and
  30  * represents the form in the transition diagram. We use the state to
  31  * determine what action to take on various user input. Actions include
  32  * things like going back / stepping forward / process etc
  33  *
  34  * @package CRM
  35  * @copyright CiviCRM LLC (c) 2004-2014
  36  * $Id$
  37  *
  38  */
  39 class CRM_Core_State {
  40
  41   /**
  42    * state name
  43    * @var string
  44    */
  45   protected $_name;
  46
  47   /**
  48    * this is a combination "OR" of the STATE_* constants defined below
  49    * @var int
  50    */
  51   protected $_type;
  52
  53   /**
  54    * the state that precedes this state
  55    * @var object
  56    */
  57   protected $_back;
  58
  59   /**
  60    * the state that succeeds this state
  61    * @var object
  62    */
  63   protected $_next;
  64
  65   /**
  66    * The state machine that this state is part of
  67    * @var object
  68    */
  69   protected $_stateMachine;
  70
  71   /**
  72    * The different types of states. As we flush out the framework more
  73    * we will introduce other conditional / looping states which will
  74    * bring in more complexity to the framework. For now, lets keep it simple
  75    * @var int
  76    */
  77   CONST START = 1, FINISH = 2, SIMPLE = 4;
  78
  79   /**
  80    * constructor
  81    *
  82    * @param $name
  83    * @param $type
  84    * @param $back
  85    * @param $next
  86    * @param $stateMachine
  87    *
  88    * @internal param \the $string internal name of the state
  89    * @internal param \the $int state type
  90    * @internal param \the $object state that precedes this state
  91    * @internal param \the $object state that follows  this state
  92    * @internal param \the $object statemachine that this states belongs to
  93    *
  94    * @return \CRM_Core_State
  95   @access public
  96    */
  97   function __construct($name, $type, $back, $next, &$stateMachine) {
  98     $this->_name = $name;
  99     $this->_type = $type;
 100     $this->_back = $back;
 101     $this->_next = $next;
 102
 103     $this->_stateMachine = &$stateMachine;
 104   }
 105
 106   function debugPrint() {
 107     CRM_Core_Error::debug("{$this->_name}, {$this->_type}", "{$this->_back}, {$this->_next}");
 108   }
 109
 110   /**
 111    * Given an CRM Form, jump to the previous page
 112    *
 113    * @param object the CRM_Core_Form element under consideration
 114    *
 115    * @return mixed does a jump to the back state
 116    * @access public
 117    */
 118   function handleBackState(&$page) {
 119     if ($this->_type & self::START) {
 120       $page->handle('display');
 121     }
 122     else {
 123       $back = &$page->controller->getPage($this->_back);
 124       return $back->handle('jump');
 125     }
 126   }
 127
 128   /**
 129    * Given an CRM Form, jump to the next page
 130    *
 131    * @param object the CRM_Core_Form element under consideration
 132    *
 133    * @return mixed does a jump to the nextstate
 134    * @access public
 135    */
 136   function handleNextState(&$page) {
 137     if ($this->_type & self::FINISH) {
 138       $page->handle('process');
 139     }
 140     else {
 141       $next = &$page->controller->getPage($this->_next);
 142       return $next->handle('jump');
 143     }
 144   }
 145
 146   /**
 147    * Determine the name of the next state. This is useful when we want
 148    * to display the navigation labels or potential path
 149    *
 150    * @return string
 151    * @access public
 152    */
 153   function getNextState() {
 154     if ($this->_type & self::FINISH) {
 155       return NULL;
 156     }
 157     else {
 158       $next = &$page->controller->getPage($this->_next);
 159       return $next;
 160     }
 161   }
 162
 163   /**
 164    * Mark this page as valid for the QFC framework. This is needed as
 165    * we build more advanced functionality into the StateMachine
 166    *
 167    * @param object the QFC data container
 168    *
 169    * @return void
 170    * @access public
 171    */
 172   function validate(&$data) {
 173     $data['valid'][$this->_name] = TRUE;
 174   }
 175
 176   /**
 177    * Mark this page as invalid for the QFC framework. This is needed as
 178    * we build more advanced functionality into the StateMachine
 179    *
 180    * @param object the QFC data container
 181    *
 182    * @return void
 183    * @access public
 184    */
 185   function invalidate(&$data) {
 186     $data['valid'][$this->_name] = NULL;
 187   }
 188
 189   /**
 190    * getter for name
 191    *
 192    * @return string
 193    * @access public
 194    */
 195   function getName() {
 196     return $this->_name;
 197   }
 198
 199   /**
 200    * setter for name
 201    *
 202    * @param string
 203    *
 204    * @return void
 205    * @access public
 206    */
 207   function setName($name) {
 208     $this->_name = $name;
 209   }
 210
 211   /**
 212    * getter for type
 213    *
 214    * @return int
 215    * @access public
 216    */
 217   function getType() {
 218     return $this->_type;
 219   }
 220 }
 221