classes/plwizard.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2011 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(&$success);
  49
  50     /** Displays the success message.
  51      */
  52     public function success();
  53 }
  54
  55 /** A PlWizard is a set of pages through which the user can navigate,
  56  * his action on a page determining which the next one will be.
  57  *
  58  * A Wizard can either a stateless wizard (which is only a set of
  59  * independent pages through which the user can easily navigate) or
  60  * stateful (a suite of steps where each step gives clue for the next
  61  * one).
  62  */
  63 class PlWizard
  64 {
  65     const FIRST_PAGE    = 'bt_first';
  66     const NEXT_PAGE     = 'bt_next';
  67     const CURRENT_PAGE  = 'bt_current';
  68     const PREVIOUS_PAGE = 'bt_previous';
  69     const LAST_PAGE     = 'bt_last';
  70
  71     private $userdata = array();
  72
  73     protected $name;
  74     protected $layout;
  75     protected $stateless;
  76     protected $ajax;
  77     protected $ajax_animated;
  78
  79     protected $pages;
  80     protected $titles;
  81     protected $lookup;
  82     protected $inv_lookup;
  83
  84     public function __construct($name, $layout, $stateless = false, $ajax = true, $ajax_animated = true)
  85     {
  86         $this->name      = 'wiz_' . $name;
  87         $this->layout    = $layout;
  88         $this->stateless = $stateless;
  89         $this->pages  = array();
  90         $this->lookup = array();
  91         $this->titles = array();
  92         $this->ajax   = $ajax;
  93         $this->ajax_animated = $ajax_animated;
  94         if (!isset($_SESSION[$this->name])) {
  95             $_SESSION[$this->name] = array();
  96             $_SESSION[$this->name . '_page']  = null;
  97             $_SESSION[$this->name . '_stack'] = array();
  98         }
  99     }
 100
 101     public function addPage($class, $title, $id = null)
 102     {
 103         if ($id == null) {
 104             $id = count($this->pages);
 105         }
 106         $this->lookup[$id]  = count($this->pages);
 107         $this->inv_lookup[] = $id;
 108         $this->pages[]      = $class;
 109         $this->titles[]     = $title;
 110     }
 111
 112     public function addUserData($name, $value)
 113     {
 114         $this->userdata[$name] = $value;
 115     }
 116
 117     public function getUserData($name, $default = null)
 118     {
 119         return $this->userdata[$name];
 120     }
 121
 122     public function set($varname, $value)
 123     {
 124         $_SESSION[$this->name][$varname] = $value;
 125     }
 126
 127     public function get($varname, $default = null)
 128     {
 129         return isset($_SESSION[$this->name][$varname]) ?
 130                     $_SESSION[$this->name][$varname] : $default;
 131     }
 132
 133     public function v($varname, $default = "")
 134     {
 135         return $this->get($varname, $default);
 136     }
 137
 138     public function i($varname, $default = 0)
 139     {
 140         return (int)$this->get($varname, $default);
 141     }
 142
 143     public function clear($varname = null)
 144     {
 145         if (is_null($varname)) {
 146             $_SESSION[$this->name] = array();
 147         } else {
 148             unset($_SESSION[$this->name][$varname]);
 149         }
 150         $_SESSION[$this->name . '_page'] = null;
 151     }
 152
 153     private function getPage($id)
 154     {
 155         $page = $this->pages[$id];
 156         return new $page($this);
 157     }
 158
 159     public function apply(PlPage $smarty, $baseurl, $pgid = null, $mode = 'normal')
 160     {
 161         if ($this->stateless && (isset($this->lookup[$pgid]) || isset($this->pages[$pgid]))) {
 162             $curpage = is_numeric($pgid) ? $pgid : $this->lookup[$pgid];
 163         } else if ($this->stateless && is_null($pgid)) {
 164             $curpage = 0;
 165         } else {
 166             $curpage = $_SESSION[$this->name . '_page'];
 167         }
 168         $oldpage = $curpage;
 169
 170         // Process the previous page
 171         if (Post::has('valid_page')) {
 172             S::assert_xsrf_token();
 173
 174             $page = $this->getPage(Post::i('valid_page'));
 175             $curpage = Post::i('valid_page');
 176             $success = false;
 177             $next = $page->process($success);
 178             $last = $curpage;
 179             switch ($next) {
 180               case PlWizard::FIRST_PAGE:
 181                 $curpage = 0;
 182                 break;
 183               case PlWizard::PREVIOUS_PAGE:
 184                 if (!$this->stateless && count($_SESSION[$this->name . '_stack'])) {
 185                     $curpage = array_pop($_SESSION[$this->name . '_stack']);
 186                 } elseif ($curpage && $this->stateless) {
 187                     $curpage--;
 188                 } else {
 189                     $curpage = 0;
 190                 }
 191                 break;
 192               case PlWizard::NEXT_PAGE:
 193                 if ($curpage < count($this->pages) - 1) {
 194                     $curpage++;
 195                 }
 196                 break;
 197               case PlWizard::LAST_PAGE:
 198                 $curpage = count($this->pages) - 1;
 199                 break;
 200               case PlWizard::CURRENT_PAGE: break; // don't change the page
 201               default:
 202                 $curpage = is_numeric($next) ? $next : $this->lookup[$next];
 203                 break;
 204             }
 205             if (!$this->stateless) {
 206                 array_push($_SESSION[$this->name . '_stack'], $last);
 207             }
 208         }
 209         if (is_null($curpage)) {
 210             $curpage = 0;
 211         }
 212
 213         // Prepare the page
 214         $_SESSION[$this->name . '_page'] = $curpage;
 215         if ($curpage != $oldpage) {
 216             if (isset($success) && $success) {
 217                 pl_redirect($baseurl . '/' . $this->inv_lookup[$curpage] . '/null/' . $success);
 218             } else {
 219                 pl_redirect($baseurl . '/' . $this->inv_lookup[$curpage]);
 220             }
 221         } else if (!isset($page)) {
 222             $page = $this->getPage($curpage);
 223         }
 224         if ($mode == 'ajax') {
 225             pl_content_headers("text/html");
 226             $smarty->changeTpl($this->layout, NO_SKIN);
 227             $smarty->assign('wiz_run_ajax', true);
 228         } else {
 229             $smarty->changeTpl($this->layout);
 230         }
 231         $smarty->assign('pages', $this->titles);
 232         $smarty->assign('current', $curpage);
 233         $smarty->assign('lookup', $this->inv_lookup);
 234         $smarty->assign('stateless', $this->stateless);
 235         $smarty->assign('wiz_baseurl', $baseurl);
 236         $smarty->assign('wiz_ajax', $this->ajax);
 237         $smarty->assign('wiz_animated', $this->ajax_animated);
 238         $smarty->assign('tab_width', (int)(99 / count($this->pages)));
 239         $smarty->assign('wiz_page', $page->template());
 240         $smarty->assign('pl_no_errors', true);
 241         $page->prepare($smarty, isset($this->inv_lookup[$curpage]) ? $this->inv_lookup[$curpage] : $curpage);
 242         if (isset($success) && $success) {
 243             $smarty->trigSuccess($page->success());
 244         }
 245     }
 246 }
 247
 248 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker fenc=utf-8:
 249 ?>