3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2014 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2014
37 * Core StateMachine. All statemachines subclass for the core one
38 * for functionality specific to their needs.
40 * A statemachine keeps track of differnt states and forms for a
41 * html quickform controller.
44 class CRM_Core_StateMachine
{
47 * The controller of this state machine
50 protected $_controller;
53 * The list of states that belong to this state machine
59 * The list of pages that belong to this state machine. Note
60 * that a state and a form have a 1 <-> 1 relationship. so u
61 * can always derive one from the other
67 * The names of the pages
71 protected $_pageNames;
74 * The mode that the state machine is operating in
77 protected $_action = NULL;
80 * The display name for this machine
83 protected $_name = NULL;
88 * @param object $controller the controller for this state machine
90 * @param \const|int $action
92 * @return \CRM_Core_StateMachine
95 public function __construct(&$controller, $action = CRM_Core_Action
::NONE
) {
96 $this->_controller
= &$controller;
97 $this->_action
= $action;
99 $this->_states
= array();
107 public function getName() {
118 public function setName($name) {
119 $this->_name
= $name;
123 * Do a state transition jump. Currently only supported types are
124 * Next and Back. The other actions (Cancel, Done, Submit etc) do
125 * not need the state machine to figure out where to go
127 * @param CRM_Core_Form $page the current form-page
128 * @param string $actionName Current action name, as one Action object can serve multiple actions
129 * @param string $type The type of transition being requested (Next or Back)
133 public function perform(&$page, $actionName, $type = 'Next') {
134 // save the form values and validation status to the session
135 $page->isFormBuilt() or $page->buildForm();
137 $pageName = $page->getAttribute('name');
138 $data = &$page->controller
->container();
140 $data['values'][$pageName] = $page->exportValues();
141 $data['valid'][$pageName] = $page->validate();
143 // if we are going to the next state
144 // Modal form and page is invalid: don't go further
145 if ($type == 'Next' && !$data['valid'][$pageName]) {
146 return $page->handle('display');
149 $state = &$this->_states
[$pageName];
151 // dont know how or why we landed here so abort and display
154 return $page->handle('display');
157 // the page is valid, process it if we are jumping to the next state
158 if ($type == 'Next') {
159 $page->mainProcess();
160 // we get the state again, since postProcess might have changed it
161 // this bug took me forever to find :) Lobo
162 $state = &$this->_states
[$pageName];
163 $state->handleNextState($page);
166 $state->handleBackState($page);
171 * Helper function to add a State to the state machine
173 * @param string $name the internal name
174 * @param int $type the type of state (START|FINISH|SIMPLE)
175 * @param object $prev the previous page if any
176 * @param object $next the next page if any
180 public function addState($name, $type, $prev, $next) {
181 $this->_states
[$name] = new CRM_Core_State($name, $type, $prev, $next, $this);
185 * Given a name find the corresponding state
187 * @param string $name the state name
189 * @return object the state object
191 public function find($name) {
192 if (array_key_exists($name, $this->_states
)) {
193 return $this->_states
[$name];
201 * Return the list of state objects
203 * @return array array of states in the state machine
205 public function getStates() {
206 return $this->_states
;
210 * Return the state object corresponding to the name
212 * @param string $name name of page
214 * @return CRM_Core_State state object matching the name
216 public function &getState($name) {
217 if (isset($this->_states
[$name])) {
218 return $this->_states
[$name];
222 * This is a gross hack for ajax driven requests where
223 * we change the form name to allow multiple edits to happen
224 * We need a cleaner way of doing this going forward
226 foreach ($this->_states
as $n => $s ) {
227 if (substr($name, 0, strlen($n)) == $n) {
236 * Return the list of form objects
238 * @return array array of pages in the state machine
240 public function getPages() {
241 return $this->_pages
;
245 * AddSequentialStates: meta level function to create a simple
246 * wizard for a state machine that is completely sequential.
249 * @param array $pages (reference ) the array of page objects
251 * @internal param array $states states is an array of arrays. Each element
252 * of the top level array describes a state. Each state description
253 * includes the name, the display name and the class name
257 public function addSequentialPages(&$pages) {
258 $this->_pages
= &$pages;
259 $numPages = count($pages);
261 $this->_pageNames
= array();
262 foreach ($pages as $tempName => $value) {
263 if (!empty($value['className'])) {
264 $this->_pageNames
[] = $tempName;
267 $this->_pageNames
[] = CRM_Utils_String
::getClassName($tempName);
272 foreach ($pages as $tempName => $value) {
273 $name = $this->_pageNames
[$i];
275 $className = CRM_Utils_Array
::value('className',
279 $classPath = str_replace('_', '/', $className) . '.php';
280 if ($numPages == 1) {
281 $prev = $next = NULL;
282 $type = CRM_Core_State
::START | CRM_Core_State
::FINISH
;
287 $next = $this->_pageNames
[$i +
1];
288 $type = CRM_Core_State
::START
;
290 elseif ($i == $numPages - 1) {
292 $prev = $this->_pageNames
[$i - 1];
294 $type = CRM_Core_State
::FINISH
;
297 // in between simple state
298 $prev = $this->_pageNames
[$i - 1];
299 $next = $this->_pageNames
[$i +
1];
300 $type = CRM_Core_State
::SIMPLE
;
303 $this->addState($name, $type, $prev, $next);
310 * Reset the state machine
314 public function reset() {
315 $this->_controller
->reset();
323 public function getAction() {
324 return $this->_action
;
330 * @param string $content the content generated by this state machine
334 public function setContent(&$content) {
335 $this->_controller
->setContent($content);
343 public function &getContent() {
344 return $this->_controller
->getContent();
350 public function getDestination() {
351 return $this->_controller
->getDestination();
357 public function getSkipRedirection() {
358 return $this->_controller
->getSkipRedirection();
364 public function fini() {
365 return $this->_controller
->fini();
371 public function cancelAction() {
372 return $this->_controller
->cancelAction();
376 * Should the controller reset the session
377 * In some cases, specifically search we want to remember
378 * state across various actions and want to go back to the
379 * beginning from the final state, but retain the same session
384 public function shouldReset() {