CRM/Core/StateMachine.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2018                                |
   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  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2018
  32  */
  33
  34 /**
  35  * Core StateMachine.
  36  *
  37  * All state machines subclass for the core one for functionality specific to their needs.
  38  *
  39  * A state machine keeps track of different states and forms for a
  40  * html quickform controller.
  41  */
  42 class CRM_Core_StateMachine {
  43
  44   /**
  45    * The controller of this state machine.
  46    * @var object
  47    */
  48   protected $_controller;
  49
  50   /**
  51    * The list of states that belong to this state machine.
  52    * @var array
  53    */
  54   protected $_states;
  55
  56   /**
  57    * The list of pages that belong to this state machine. Note
  58    * that a state and a form have a 1 <-> 1 relationship. so u
  59    * can always derive one from the other
  60    * @var array
  61    */
  62   protected $_pages;
  63
  64   /**
  65    * The names of the pages.
  66    *
  67    * @var array
  68    */
  69   protected $_pageNames;
  70
  71   /**
  72    * The mode that the state machine is operating in.
  73    * @var int
  74    */
  75   protected $_action = NULL;
  76
  77   /**
  78    * The display name for this machine.
  79    * @var string
  80    */
  81   protected $_name = NULL;
  82
  83   /**
  84    * Class constructor.
  85    *
  86    * @param object $controller
  87    *   The controller for this state machine.
  88    *
  89    * @param \const|int $action
  90    *
  91    * @return \CRM_Core_StateMachine
  92    */
  93   public function __construct(&$controller, $action = CRM_Core_Action::NONE) {
  94     $this->_controller = &$controller;
  95     $this->_action = $action;
  96
  97     $this->_states = array();
  98   }
  99
 100   /**
 101    * Getter for name.
 102    *
 103    * @return string
 104    */
 105   public function getName() {
 106     return $this->_name;
 107   }
 108
 109   /**
 110    * Setter for name.
 111    *
 112    * @param string $name
 113    */
 114   public function setName($name) {
 115     $this->_name = $name;
 116   }
 117
 118   /**
 119    * Do a state transition jump.
 120    *
 121    * Currently only supported types are
 122    * Next and Back. The other actions (Cancel, Done, Submit etc) do
 123    * not need the state machine to figure out where to go
 124    *
 125    * @param CRM_Core_Form $page
 126    *   The current form-page.
 127    * @param string $actionName
 128    *   Current action name, as one Action object can serve multiple actions.
 129    * @param string $type
 130    *   The type of transition being requested (Next or Back).
 131    *
 132    * @return object
 133    */
 134   public function perform(&$page, $actionName, $type = 'Next') {
 135     // save the form values and validation status to the session
 136     $page->isFormBuilt() or $page->buildForm();
 137
 138     $pageName = $page->getAttribute('name');
 139     $data = &$page->controller->container();
 140
 141     $data['values'][$pageName] = $page->exportValues();
 142     $data['valid'][$pageName] = $page->validate();
 143
 144     // if we are going to the next state
 145     // Modal form and page is invalid: don't go further
 146     if ($type == 'Next' && !$data['valid'][$pageName]) {
 147       return $page->handle('display');
 148     }
 149
 150     $state = &$this->_states[$pageName];
 151
 152     // dont know how or why we landed here so abort and display
 153     // current page
 154     if (empty($state)) {
 155       return $page->handle('display');
 156     }
 157
 158     // the page is valid, process it if we are jumping to the next state
 159     if ($type == 'Next') {
 160       $page->mainProcess();
 161       // we get the state again, since postProcess might have changed it
 162       // this bug took me forever to find :) Lobo
 163       $state = &$this->_states[$pageName];
 164       $state->handleNextState($page);
 165     }
 166     else {
 167       $state->handleBackState($page);
 168     }
 169   }
 170
 171   /**
 172    * Helper function to add a State to the state machine.
 173    *
 174    * @param string $name
 175    *   The internal name.
 176    * @param int $type
 177    *   The type of state (START|FINISH|SIMPLE).
 178    * @param object $prev
 179    *   The previous page if any.
 180    * @param object $next
 181    *   The next page if any.
 182    */
 183   public function addState($name, $type, $prev, $next) {
 184     $this->_states[$name] = new CRM_Core_State($name, $type, $prev, $next, $this);
 185   }
 186
 187   /**
 188    * Given a name find the corresponding state.
 189    *
 190    * @param string $name
 191    *   The state name.
 192    *
 193    * @return object
 194    *   the state object
 195    */
 196   public function find($name) {
 197     if (array_key_exists($name, $this->_states)) {
 198       return $this->_states[$name];
 199     }
 200     else {
 201       return NULL;
 202     }
 203   }
 204
 205   /**
 206    * Return the list of state objects.
 207    *
 208    * @return array
 209    *   array of states in the state machine
 210    */
 211   public function getStates() {
 212     return $this->_states;
 213   }
 214
 215   /**
 216    * Return the state object corresponding to the name.
 217    *
 218    * @param string $name
 219    *   Name of page.
 220    *
 221    * @return CRM_Core_State
 222    *   state object matching the name
 223    */
 224   public function &getState($name) {
 225     if (isset($this->_states[$name])) {
 226       return $this->_states[$name];
 227     }
 228
 229     /*
 230      * This is a gross hack for ajax driven requests where
 231      * we change the form name to allow multiple edits to happen
 232      * We need a cleaner way of doing this going forward
 233      */
 234     foreach ($this->_states as $n => $s) {
 235       if (substr($name, 0, strlen($n)) == $n) {
 236         return $s;
 237       }
 238     }
 239
 240     return NULL;
 241   }
 242
 243   /**
 244    * Return the list of form objects.
 245    *
 246    * @return array
 247    *   array of pages in the state machine
 248    */
 249   public function getPages() {
 250     return $this->_pages;
 251   }
 252
 253   /**
 254    * Add sequential pages.
 255    *
 256    * Meta level function to create a simple wizard for a state machine that is completely sequential.
 257    *
 258    * @param array $pages
 259    *   (reference ) the array of page objects.
 260    */
 261   public function addSequentialPages(&$pages) {
 262     $this->_pages = &$pages;
 263     $numPages = count($pages);
 264
 265     $this->_pageNames = array();
 266     foreach ($pages as $tempName => $value) {
 267       if (!empty($value['className'])) {
 268         $this->_pageNames[] = $tempName;
 269       }
 270       else {
 271         $this->_pageNames[] = CRM_Utils_String::getClassName($tempName);
 272       }
 273     }
 274
 275     $i = 0;
 276     foreach ($pages as $tempName => $value) {
 277       $name = $this->_pageNames[$i];
 278
 279       $className = CRM_Utils_Array::value('className',
 280         $value,
 281         $tempName
 282       );
 283       $classPath = str_replace('_', '/', $className) . '.php';
 284       if ($numPages == 1) {
 285         $prev = $next = NULL;
 286         $type = CRM_Core_State::START | CRM_Core_State::FINISH;
 287       }
 288       elseif ($i == 0) {
 289         // start state
 290         $prev = NULL;
 291         $next = $this->_pageNames[$i + 1];
 292         $type = CRM_Core_State::START;
 293       }
 294       elseif ($i == $numPages - 1) {
 295         // finish state
 296         $prev = $this->_pageNames[$i - 1];
 297         $next = NULL;
 298         $type = CRM_Core_State::FINISH;
 299       }
 300       else {
 301         // in between simple state
 302         $prev = $this->_pageNames[$i - 1];
 303         $next = $this->_pageNames[$i + 1];
 304         $type = CRM_Core_State::SIMPLE;
 305       }
 306
 307       $this->addState($name, $type, $prev, $next);
 308
 309       $i++;
 310     }
 311   }
 312
 313   /**
 314    * Reset the state machine.
 315    */
 316   public function reset() {
 317     $this->_controller->reset();
 318   }
 319
 320   /**
 321    * Getter for action.
 322    *
 323    * @return int
 324    */
 325   public function getAction() {
 326     return $this->_action;
 327   }
 328
 329   /**
 330    * Setter for content.
 331    *
 332    * @param string $content
 333    *   The content generated by this state machine.
 334    */
 335   public function setContent(&$content) {
 336     $this->_controller->setContent($content);
 337   }
 338
 339   /**
 340    * Getter for content.
 341    *
 342    * @return string
 343    */
 344   public function &getContent() {
 345     return $this->_controller->getContent();
 346   }
 347
 348   /**
 349    * @return mixed
 350    */
 351   public function getDestination() {
 352     return $this->_controller->getDestination();
 353   }
 354
 355   /**
 356    * @return mixed
 357    */
 358   public function getSkipRedirection() {
 359     return $this->_controller->getSkipRedirection();
 360   }
 361
 362   /**
 363    * @return mixed
 364    */
 365   public function fini() {
 366     return $this->_controller->fini();
 367   }
 368
 369   /**
 370    * @return mixed
 371    */
 372   public function cancelAction() {
 373     return $this->_controller->cancelAction();
 374   }
 375
 376   /**
 377    * Should the controller reset the session
 378    * In some cases, specifically search we want to remember
 379    * state across various actions and want to go back to the
 380    * beginning from the final state, but retain the same session
 381    * values
 382    *
 383    * @return bool
 384    */
 385   public function shouldReset() {
 386     return TRUE;
 387   }
 388
 389 }