classes/plset.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
  23 /** UserSet is a light-weight Model/View tool for displaying a set of items
  24  */
  25 abstract class PlSet
  26 {
  27     const DEFAULT_MAX_RES = 20;
  28
  29     protected $conds   = null;
  30     protected $orders  = array();
  31     protected $limit   = null;
  32
  33     protected $count   = null;
  34
  35     // A list of available views
  36     private $mods      = array();
  37     // An array of $view_name => array($parameters)
  38     private $modParams = array();
  39     // The current view name
  40     private $mod       = null;
  41     // The default view name
  42     private $default   = null;
  43
  44     public function __construct(PlFilterCondition &$cond, $orders = null)
  45     {
  46         if ($cond instanceof PFC_And) {
  47             $this->conds = $cond;
  48         } else {
  49             $this->conds = new PFC_And($cond);
  50         }
  51
  52         if (!is_null($orders) && $orders instanceof PlFilterOrder) {
  53             $this->addSort($orders);
  54         } else if (is_array($orders)){
  55             foreach ($orders as $order) {
  56                 $this->addSort($order);
  57             }
  58         }
  59     }
  60
  61     /** Adds a new view (minifiche, trombi, map)
  62      * @param $name The name of the view (cf buildView)
  63      * @param $description A user-friendly name for the view
  64      * @param $default Whether this is the default view
  65      * @param $params Parameters used to tune the view (display promo, order by
  66      *                  score...)
  67      */
  68     public function addMod($name, $description, $default = false, array $params = array())
  69     {
  70         $name = strtolower($name);
  71         $this->mods[$name]      = $description;
  72         $this->modParams[$name] = $params;
  73         if ($default) {
  74             $this->default = $name;
  75         }
  76     }
  77
  78     public function rmMod($name)
  79     {
  80         $name = strtolower($name);
  81         unset($this->mods[$name]);
  82     }
  83
  84     /** Adds a new sort (on the PlFilter)
  85      */
  86     public function addSort(PlFilterOrder &$order)
  87     {
  88         $this->orders[] = $order;
  89     }
  90
  91     /** Adds a new condition to the PlFilter
  92      */
  93     public function addCond(PlFilterCondition &$cond)
  94     {
  95         $this->conds->addChild($cond);
  96     }
  97
  98     /** This function builds the right kind of PlFilter from given data
  99      * @param $cond The PlFilterCondition for the filter
 100      * @param $orders An array of PlFilterOrder for the filter
 101      */
 102     abstract protected function buildFilter(PlFilterCondition &$cond, $orders);
 103
 104     /** This function returns the results of the given filter
 105      * wihtin $limit; can be use to replace the default $pf->get call.
 106      * @param &$pf The filter
 107      * @param $limit The PlLimit
 108      * @return The results of the filter
 109      */
 110     protected function &getFilterResults(PlFilter &$pf, PlLimit $limit)
 111     {
 112         $res = $pf->get($limit);
 113         return $res;
 114     }
 115
 116     /** Helper function, calls buildFilter with the adequate condition/orders.
 117      * @param $orders Additional orders to use before the default ones.
 118      * @return A newly created PlFilter.
 119      */
 120     private function buildFilterHelper($orders = array())
 121     {
 122         if (!is_array($orders)) {
 123             $orders = array($orders);
 124         }
 125         $orders = array_merge($orders, $this->orders);
 126
 127         return $this->buildFilter($this->conds, $orders);
 128     }
 129
 130     /** This function returns the values of the set, and sets $count with the
 131      * total number of results.
 132      * @param $limit A PlLimit for selecting users
 133      * @param $orders An optional array of PFO to use before the "default" ones
 134      * @return The result of $pf->get();
 135      */
 136     public function &get(PlLimit $limit = null, $orders = array())
 137     {
 138         if (is_null($limit)) {
 139             $limit = new PlLimit(self::DEFAULT_MAX_RES, 0);
 140         }
 141         $pf = $this->buildFilterHelper($orders);
 142         $it = $this->getFilterResults($pf, $limit);
 143         $this->count = $pf->getTotalCount();
 144         return $it;
 145     }
 146
 147     /** This function returns the ids of the set, and sets $count with the
 148      * total number of results.
 149      * @param $limit A PlLimit for selecting profiles
 150      * @param $orders An optional array of PFO to use before the "default" ones
 151      * @return The result of $pf->getId();
 152      */
 153     public function &getIds(PlLimit $limit = null, $orders = array())
 154     {
 155         if (is_null($limit)) {
 156             $limit = new PlLimit(self::DEFAULT_MAX_RES, 0);
 157         }
 158         $pf = $this->buildFilterHelper($orders);
 159         $result = $pf->getIds($limit);
 160         $this->count = count($result);
 161         return $result;
 162     }
 163
 164     /** Return an array containing all pertinent parameters for this page
 165      * Generated from $_GET, after some cleanup (remove 'n' (plat/al field
 166      * for the handler path)
 167      */
 168     public function args()
 169     {
 170         $get = $_GET;
 171         unset($get['n']);
 172         return $get;
 173     }
 174
 175     /** Convert an array into an URL query (?foo=bar)
 176      * @param $args An associative array to convert to a query string
 177      * @param $encode Whether to url-encode the string
 178      */
 179     protected function encodeArgs(array $args, $encode = false)
 180     {
 181         $qs = '?';
 182         $sep = '&';
 183         foreach ($args as $k=>$v) {
 184             if (!$encode) {
 185                 $k = urlencode($k);
 186                 $v = urlencode($v);
 187             }
 188             $qs .= "$k=$v$sep";
 189         }
 190         return $encode ? urlencode($qs) : $qs;
 191     }
 192
 193     public function count()
 194     {
 195         return $this->count;
 196     }
 197
 198     /** Builds the view class from the given parameters
 199      * @param $view A string ('profile' for 'ProfileView'); if null,
 200      *          the default view is used.
 201      * @return A new PlView instance.
 202      */
 203     private function &buildView($view)
 204     {
 205         $view = strtolower($view);
 206         if (!$view || !class_exists($view . 'View') || !isset($this->mods[$view])) {
 207             reset($this->mods);
 208             $view = $this->default ? $this->default : key($this->mods);
 209         }
 210         $this->mod = $view;
 211         $class = $view . 'View';
 212         if (!class_exists($class)) {
 213             $view = null;
 214         } else {
 215             $view = new $class($this, $this->modParams[$this->mod]);
 216             if (!$view instanceof PlView) {
 217                 $view = null;
 218             }
 219         }
 220         return $view;
 221     }
 222
 223     /** Creates the view: sets the page template, assigns Smarty vars.
 224      * @param $baseurl The base URL for this (for instance, "search/")
 225      * @param $page The page in which the view should be loaded
 226      * @param $view The name of the view; if null, the default one will be used.
 227      */
 228     public function apply($baseurl, PlPage &$page, $view = null)
 229     {
 230         $view =& $this->buildView($view);
 231         if (is_null($view)) {
 232             return false;
 233         }
 234         $args = $view->args();
 235         $page->coreTpl('plset.tpl');
 236         $page->assign('plset_base', $baseurl);
 237         $page->assign('plset_mods', $this->mods);
 238         $page->assign('plset_mod', $this->mod);
 239         $page->assign('plset_args', $this->encodeArgs($args));
 240         $page->assign('plset_args_enc', $this->encodeArgs($args, true));
 241         foreach ($this->modParams[$this->mod] as $param=>$value) {
 242             $page->assign($this->mod . '_' . $param, $value);
 243         }
 244         $page->assign('plset_content', $view->apply($page));
 245         $page->assign('plset_count', $this->count);
 246         return true;
 247     }
 248 }
 249
 250 interface PlView
 251 {
 252     /** Constructs a new PlView
 253      * @param $set The set
 254      * @param $params Parameters to tune the view (sort by score, include promo...)
 255      */
 256     public function __construct(PlSet &$set, array $params);
 257
 258     /** Applies the view to a page
 259      * The content of the set is fetched here.
 260      * @param $page Page to which the view will be applied
 261      * @return The name of the global view template (for displaying the view,
 262      *              not the items of the set)
 263      */
 264     public function apply(PlPage &$page);
 265
 266     /** As PlSet->args(), returns the ?foo=bar part of the URL for generating
 267      * this PlSet, after adding the necessary components and removing useless ones.
 268      */
 269     public function args();
 270 }
 271
 272 /** This class describes an Order as used in a PlView :
 273  * - It is based on a PlFilterOrder
 274  * - It has a short identifier
 275  * - It has a full name, to display on the page
 276  */
 277 class PlViewOrder
 278 {
 279     public $pfos        = null;
 280     public $name        = null;
 281     public $displaytext = null;
 282
 283     /** Build a PlViewOrder
 284      * @param $name Name of the order (key)
 285      * @param $displaytext Text to display
 286      * @param $pfos Array of PlFilterOrder for the order
 287      */
 288     public function __construct($name, $pfos, $displaytext = null)
 289     {
 290         $this->name = $name;
 291         if (is_null($displaytext)) {
 292             $this->displaytext = ucfirst($name);
 293         } else {
 294             $this->displaytext = $displaytext;
 295         }
 296         $this->pfos = $pfos;
 297     }
 298 }
 299
 300 abstract class MultipageView implements PlView
 301 {
 302     protected $set;
 303
 304     public $pages  = 1;
 305     public $page   = 1;
 306     public $offset = 0;
 307
 308     protected $entriesPerPage = 20;
 309     protected $params = array();
 310
 311     protected $sortkeys = array();
 312     protected $defaultkey = null;
 313
 314     protected $bound_field = null;
 315
 316     /** Builds a MultipageView
 317      * @param $set The associated PlSet
 318      * @param $params Parameters of the view
 319      */
 320     public function __construct(PlSet &$set, array $params)
 321     {
 322         $this->set   =& $set;
 323         $this->page   = Env::i('page', 1);
 324         $this->offset = $this->entriesPerPage * ($this->page - 1);
 325         $this->params = $params;
 326     }
 327
 328     /** Add an order to the view
 329      */
 330     protected function addSort(PlViewOrder &$pvo, $default = false)
 331     {
 332         $this->sortkeys[$pvo->name] = $pvo;
 333         if (!$this->defaultkey || $default) {
 334             $this->defaultkey = $pvo->name;
 335         }
 336     }
 337
 338     /** Returns a list of PFO objects in accordance with the user's choice
 339      */
 340     public function order()
 341     {
 342         $order = Env::v('order', $this->defaultkey);
 343         $invert = ($order{0} == '-');
 344         if ($invert) {
 345             $order = substr($order, 1);
 346         }
 347
 348         $ordering = $this->sortkeys[$order];
 349         if ($invert) {
 350             foreach ($ordering->pfos as $pfo) {
 351                 $pfo->toggleDesc();
 352             }
 353         }
 354         return $ordering->pfos;
 355     }
 356
 357     /** Returns information on the order of bounds
 358      * @return * 1  if normal bounds
 359      *         * -1 if inversed bounds
 360      *         * 0  if bounds shouldn't be displayed
 361      */
 362     public function bounds()
 363     {
 364         return null;
 365     }
 366
 367     public function limit()
 368     {
 369         return new PlLimit($this->entriesPerPage, $this->offset);
 370     }
 371
 372     /** Name of the template to use for displaying items of the view
 373      * e.g plview.minifiche.tpl, plview.trombi.pl, ...
 374      */
 375     abstract public function templateName();
 376
 377     /** Returns the value of a boundary of the current view (in order
 378      * to show "from C to F")
 379      * @param $obj The boundary result whose value must be shown to the user
 380      *              (e.g a Profile, ...)
 381      * @return The bound
 382      */
 383     abstract protected function getBoundValue($obj);
 384
 385     public function apply(PlPage &$page)
 386     {
 387         foreach ($this->order() as $order) {
 388             if (!is_null($order)) {
 389                 $this->set->addSort($order);
 390             }
 391         }
 392         $res = $this->set->get($this->limit());
 393
 394         $show_bounds = $this->bounds();
 395         if ($show_bounds) {
 396             $start = current($res);
 397             $end   = end($res);
 398             if ($show_bounds == 1) {
 399                 $first = $this->getBoundValue($start);
 400                 $last  = $this->getBoundValue($end);
 401             } elseif ($show_bounds == -1) {
 402                 $first = $this->getBoundValue($end);
 403                 $last  = $this->getBoundValue($start);
 404             }
 405             $page->assign('first', $first);
 406             $page->assign('last', $last);
 407         }
 408
 409         $page->assign('show_bounds', $show_bounds);
 410         $page->assign('order', Env::v('order', $this->defaultkey));
 411         $page->assign('orders', $this->sortkeys);
 412         $page->assign_by_ref('plview', $this);
 413         if (is_array($res)) {
 414             $page->assign('set_keys', array_keys($res));
 415         }
 416         $page->assign_by_ref('set', $res);
 417         $count = $this->set->count();
 418         $this->pages = intval(ceil($count / $this->entriesPerPage));
 419         return PlPage::getCoreTpl('plview.multipage.tpl');
 420     }
 421
 422     /** Arguments are those needed by the set, minus 'page' and 'order' which
 423      * will be set to new values in the html links.
 424      */
 425     public function args()
 426     {
 427         $list = $this->set->args();
 428         unset($list['page']);
 429         unset($list['order']);
 430         return $list;
 431     }
 432 }
 433
 434 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 435 ?>