classes/plwizard.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2008 Polytechnique.org                              *
   4  *  http://opensource.polytechnique.org/                                   *
   5  *                                                                         *
   6  *  This program is free software; you can redistribute it and/or modify   *
   7  *  it under the terms of the GNU General Public License as published by   *
   8  *  the Free Software Foundation; either version 2 of the License, or      *
   9  *  (at your option) any later version.                                    *
  10  *                                                                         *
  11  *  This program is distributed in the hope that it will be useful,        *
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
  14  *  GNU General Public License for more details.                           *
  15  *                                                                         *
  16  *  You should have received a copy of the GNU General Public License      *
  17  *  along with this program; if not, write to the Free Software            *
  18  *  Foundation, Inc.,                                                      *
  19  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                *
  20  **************************************************************************/
  21
  22 /** A Wizard Page is a page of a wizard. It is a self-contained step which
  23  * handles both the creation and initialisation of the step (by using the
  24  * Wizard global state, if needed) and the processing of the action the
  25  * user made on it.
  26  */
  27 interface PlWizardPage
  28 {
  29     /** Build a new instance of the class
  30      * associated with the given wizard master.
  31      */
  32     public function __construct(PlWizard &$wiz);
  33
  34     /** Return the name of the templace describing the page.
  35      */
  36     public function template();
  37
  38     /** Prepare the page by assigning to it any useful value.
  39      */
  40     public function prepare(PlPage &$page, $id);
  41
  42     /** Process information resulting of the application of the page.
  43      * This function must return a clue indicating the next page to show.
  44      * This clue can be either a page id, a page number or a navigation
  45      * id (PlWizard::FIRST_PAGE, PlWizard::NEXT_PAGE, PlWizard::CURRENT_PAGE
  46      *  PlWizard::PREVIOUS_PAGE, PlWizard::LAST_PAGE).
  47      */
  48     public function process();
  49 }
  50
  51 /** A PlWizard is a set of pages through which the user can navigate,
  52  * his action on a page determining which the next one will be.
  53  *
  54  * A Wizard can either a stateless wizard (which is only a set of
  55  * independent pages through which the user can easily navigate) or
  56  * stateful (a suite of steps where each step gives clue for the next
  57  * one).
  58  */
  59 class PlWizard
  60 {
  61     const FIRST_PAGE    = 'bt_first';
  62     const NEXT_PAGE     = 'bt_next';
  63     const CURRENT_PAGE  = 'bt_current';
  64     const PREVIOUS_PAGE = 'bt_previous';
  65     const LAST_PAGE     = 'bt_last';
  66
  67     protected $name;
  68     protected $layout;
  69     protected $stateless;
  70     protected $ajax;
  71
  72     protected $pages;
  73     protected $titles;
  74     protected $lookup;
  75     protected $inv_lookup;
  76
  77     public function __construct($name, $layout, $stateless = false, $ajax = true)
  78     {
  79         $this->name      = 'wiz_' . $name;
  80         $this->layout    = $layout;
  81         $this->stateless = $stateless;
  82         $this->pages  = array();
  83         $this->lookup = array();
  84         $this->titles = array();
  85         $this->ajax   = $ajax;
  86         if (!isset($_SESSION[$this->name])) {
  87             $_SESSION[$this->name] = array();
  88             $_SESSION[$this->name . '_page']  = null;
  89             $_SESSION[$this->name . '_stack'] = array();
  90         }
  91     }
  92
  93     public function addPage($class, $title, $id = null)
  94     {
  95         if ($id == null) {
  96             $id = count($this->pages);
  97         }
  98         $this->lookup[$id]  = count($this->pages);
  99         $this->inv_lookup[] = $id;
 100         $this->pages[]      = $class;
 101         $this->titles[]     = $title;
 102     }
 103
 104     public function set($varname, $value)
 105     {
 106         $_SESSION[$this->name][$varname] = $value;
 107     }
 108
 109     public function get($varname, $default = null)
 110     {
 111         return isset($_SESSION[$this->name][$varname]) ?
 112                     $_SESSION[$this->name][$varname] : $default;
 113     }
 114
 115     public function v($varname, $default = "")
 116     {
 117         return $this->get($varname, $default);
 118     }
 119
 120     public function i($varname, $default = 0)
 121     {
 122         return (int)$this->get($varname, $default);
 123     }
 124
 125     public function clear($varname = null)
 126     {
 127         if (is_null($varname)) {
 128             $_SESSION[$this->name] = array();
 129         } else {
 130             unset($_SESSION[$this->name][$varname]);
 131         }
 132         $_SESSION[$this->name . '_page'] = null;
 133     }
 134
 135     private function getPage($id)
 136     {
 137         $page = $this->pages[$id];
 138         return new $page($this);
 139     }
 140
 141     public function apply(PlPage &$smarty, $baseurl, $pgid = null, $mode = 'normal')
 142     {
 143         if ($this->stateless && (isset($this->lookup[$pgid]) || isset($this->pages[$pgid]))) {
 144             $curpage = is_numeric($pgid) ? $pgid : $this->lookup[$pgid];
 145         } else if ($this->stateless && is_null($pgid)) {
 146             $curpage = 0;
 147         } else {
 148             $curpage = $_SESSION[$this->name . '_page'];
 149         }
 150         $oldpage = $curpage;
 151
 152         // Process the previous page
 153         if (Post::has('valid_page')) {
 154             S::assert_xsrf_token();
 155
 156             $page = $this->getPage(Post::i('valid_page'));
 157             $curpage = Post::i('valid_page');
 158             $next = $page->process();
 159             $last = $curpage;
 160             switch ($next) {
 161               case PlWizard::FIRST_PAGE:
 162                 $curpage = 0;
 163                 break;
 164               case PlWizard::PREVIOUS_PAGE:
 165                 if (!$this->stateless && count($_SESSION[$this->name . '_stack'])) {
 166                     $curpage = array_pop($_SESSION[$this->name . '_stack']);
 167                 } elseif ($curpage && $this->stateless) {
 168                     $curpage--;
 169                 } else {
 170                     $curpage = 0;
 171                 }
 172                 break;
 173               case PlWizard::NEXT_PAGE:
 174                 if ($curpage < count($this->pages) - 1) {
 175                     $curpage++;
 176                 }
 177                 break;
 178               case PlWizard::LAST_PAGE:
 179                 $curpage = count($this->pages) - 1;
 180                 break;
 181               case PlWizard::CURRENT_PAGE: break; // don't change the page
 182               default:
 183                 $curpage = is_numeric($next) ? $next : $this->lookup[$next];
 184                 break;
 185             }
 186             if (!$this->stateless) {
 187                 array_push($_SESSION[$this->name . '_stack'], $last);
 188             }
 189         }
 190         if (is_null($curpage)) {
 191             $curpage = 0;
 192         }
 193
 194         // Prepare the page
 195         $_SESSION[$this->name . '_page'] = $curpage;
 196         if ($curpage != $oldpage) {
 197             pl_redirect($baseurl . '/' . $this->inv_lookup[$curpage]);
 198         } else if (!isset($page)) {
 199             $page = $this->getPage($curpage);
 200         }
 201         if ($mode == 'ajax') {
 202             header('Content-Type: text/html; charset=utf-8');
 203             $smarty->changeTpl($page->template(), NO_SKIN);
 204         } else {
 205             $smarty->changeTpl($this->layout);
 206         }
 207         $smarty->assign('pages', $this->titles);
 208         $smarty->assign('current', $curpage);
 209         $smarty->assign('lookup', $this->inv_lookup);
 210         $smarty->assign('stateless', $this->stateless);
 211         $smarty->assign('wiz_baseurl', $baseurl);
 212         $smarty->assign('wiz_ajax', $this->ajax);
 213         $smarty->assign('tab_width', (int)(99 / count($this->pages)));
 214         $smarty->assign('wiz_page', $page->template());
 215         $smarty->assign('pl_no_errors', true);
 216         $page->prepare($smarty, isset($this->inv_lookup[$curpage]) ? $this->inv_lookup[$curpage] : $curpage);
 217     }
 218 }
 219
 220 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 221 ?>