Source for file List.class.php

Documentation is available at List.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Template
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Template List Class (Special class for saving lists of data)
  22.  * 
  23.  * This is a Special Template Element designed to hold lists of data.  The
  24.  * output is formatted specifically by the child class.
  25.  * 
  26.  * For example, using a string replacement Engine, looping through an array
  27.  * of data requires clever programming.  However, the List class will hold the
  28.  * array of data and perform the loop internally, formatting the desired output.
  29.  * If the program requires placing list items 'li' inside an [un]ordered list
  30.  * 'ul' or 'ol', simply populate the List_Item class with the data and assign
  31.  * a Template Variable.  When the Template File is parsed, the List object
  32.  * will replace the keyword with a formatted string.
  33.  * 
  34.  * <pre>
  35.  * $tpl = new Gumbo_Template_Engine_[Name] ();
  36.  * ...
  37.  * $tpl_list = new Gumbo_Template_List_Item;
  38.  * $tpl_list->add ("some data");
  39.  * ...
  40.  * $tpl->assign ("My_List", $tpl_list);
  41.  * 
  42.  * // inside template_file.txt
  43.  * ...
  44.  * {My_List}
  45.  * </pre>
  46.  * 
  47.  * To extend, create new List classes that work with specific types of elements.
  48.  * In HTML, this could be definition lists, table rows, [un]ordered list items,
  49.  * etc.
  50.  *
  51.  * @category Gumbo
  52.  * @package Template
  53.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  54.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  55.  * @author Michael Luster <mluster79@yahoo.com>
  56.  * @link http://sourceforge.net/projects/phpgumbo
  57.  * @desc Template List Class (Special class for saving lists of data)
  58.  * @version 0.0.1
  59.  */
  60.  
  61. gumbo_load ("Interface_Output");
  62.  
  63. abstract class Gumbo_Template_List implements Gumbo_Interface_Output {
  64.     
  65.     /** @var array $_elements string elements to place inside list item */
  66.     protected $_elements = array ();
  67.     
  68.     
  69.     
  70.     /** ABSTRACT METHODS **/
  71.     /**
  72.      * Adds data to the end of the list
  73.      * @param arr[] $data data arguments
  74.      */
  75.     abstract public function add ($data);
  76.     
  77.     /**
  78.      * Places data at the specified location
  79.      * @param int $position 
  80.      * @param arr[] $data data arguments
  81.      */
  82.     abstract public function place ($position, $data);
  83.     
  84.     
  85.     
  86.     /** ACTION METHODS **/
  87.     /**
  88.      * Displays to the browser
  89.      */
  90.     public function display () {
  91.         echo $this->fetch ();
  92.     }
  93.     
  94.     /**
  95.      * Removes data from a given position (resets the List)
  96.      * @param int $position 
  97.      * @throws Gumbo_Exception
  98.      */
  99.     public function remove ($position) {
  100.         try {
  101.             // verify precondition
  102.             if (!is_numeric ($position)) {
  103.                 throw new Gumbo_Exception ("Invalid Argument 'position:int' => {$position}:" . gettype ($position));
  104.             }
  105.             $position = (int) $position;
  106.             if ($position < 0 || $position > count ($this->getElements ())) {
  107.                 throw new Gumbo_Exception ("Invalid Range: Greater Than Zero, Less Than Total Elements: {$position}");
  108.             }
  109.             
  110.             $data = $this->getElements ();
  111.             $this->_elements = array ();
  112.             
  113.             foreach ($data as $key=>$val) {
  114.                 if ($position == $key+1) { continue; }
  115.                 $this->_elements [] = $val;
  116.             }
  117.         } catch (Gumbo_Exception $e) {
  118.             $e->setFunction (__METHOD__);
  119.             gumbo_trigger ($e);
  120.         }
  121.     }
  122.     
  123.     
  124.     
  125.     /** ACCESSOR METHODS **/
  126.     /**
  127.      * Returns all the elements
  128.      * @return array 
  129.      */
  130.     public function getElements () {
  131.         return $this->_elements;
  132.     }
  133.     
  134. }
  135.  
  136. ?>