Source for file Special.class.php

Documentation is available at Special.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.  * Special Abstract Template Class
  22.  * 
  23.  * This is a special element of Templates.  It will typically define a part of the
  24.  * program that commonly appears on every View.  The best example is a Header and
  25.  * Footer.  There can only be one Special Template element.  All Special Template
  26.  * classes should implement Singleton.  This will make the object accessible
  27.  * everywhere.
  28.  * 
  29.  * For example, if the Header defines a navigation menu that changes with the
  30.  * different areas of an application.  Each area has a special menu it defines.
  31.  * The Special_Header would load the main menu by default, allowing the application
  32.  * to change the menu as necessary.  This is a simple example (if the program uses
  33.  * menus).  The programmer could simply define a Special_Menu class.  It depends
  34.  * on the application needs.
  35.  * 
  36.  * The Special elements could be processed when outputting the main Template contents,
  37.  * or by simply assigning the element to a Template_Engine and defining it's location
  38.  * inside the Template file.  It's really at the programmer's discretion.
  39.  * 
  40.  * ELEMENTS
  41.  * These are special objects (Gumbo_Template_Engine) that are assigned to the
  42.  * Special Template.  By assigning an Element, the program can manipulate the object
  43.  * by retrieving the element.  This will separate standard Template variable
  44.  * assignment from element assignment.  It ensures that the returning element is
  45.  * a Gumbo_Template_Engine.
  46.  * 
  47.  * BASIC FILE (optional)
  48.  * This file is loaded when the Special Template object is inactive.  If no file
  49.  * is defined, the output should be blank.  The basic file is a cut-down version
  50.  * or simplified display.  For example, the main Header is used for the primary
  51.  * website, but the basic Header is used to show a printable view on screen.  (This
  52.  * should be handled with CSS, but it's a quick example).
  53.  *
  54.  * @category Gumbo
  55.  * @package Template
  56.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  57.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  58.  * @author Michael Luster <mluster79@yahoo.com>
  59.  * @link http://sourceforge.net/projects/phpgumbo
  60.  * @desc Special Abstract Template Class
  61.  * @version 0.0.1
  62.  */
  63.  
  64. gumbo_load ("Interface_Output");
  65. gumbo_load ("Template_Engine");
  66.  
  67. abstract class Gumbo_Template_Special implements Gumbo_Interface_Output {
  68.     
  69.     /** @var Gumbo_Template_Engine $_engine */
  70.     private $_engine;
  71.     
  72.     /** @var Gumbo_Interface_Output[] $_elements special Output elements */
  73.     private $_elements = array ();
  74.     
  75.     /** @var string $_file standard file */
  76.     private $_file;
  77.     /** @var string $_file_basic basic file */
  78.     private $_file_basic;
  79.     
  80.     /** @var bool $_active if standard mode is active */
  81.     private $_active = true;
  82.     
  83.     
  84.     
  85.     /** ACTION METHODS **/
  86.     /**
  87.      * Displays the formatted template file
  88.      */
  89.     public function display () {
  90.         echo $this->fetch ();
  91.     }
  92.     
  93.     /**
  94.      * Assigns a template variable with a value (wrapper to Gumbo_Template_Engine::assign())
  95.      * @param string|array$key template file reference
  96.      * @param mixed $val 
  97.      */
  98.     public function assign ($key, $val=null) {
  99.         $this->getEngine ()->assign ($key, $val);
  100.     }
  101.     
  102.     /**
  103.      * Assigns an Element to the template
  104.      * @param string $key 
  105.      * @param Gumbo_Template_Engine $obj 
  106.      * @throws Gumbo_Exception
  107.      */
  108.     public function assignElement ($key, Gumbo_Template_Engine $obj) {
  109.         try {
  110.             // verify precondition
  111.             if (!is_string ($key)) {
  112.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  113.             }
  114.             
  115.             $this->_elements [$key] = $obj;
  116.         } catch (Gumbo_Exception $e) {
  117.             $e->setFunction (__METHOD__);
  118.             gumbo_trigger ($e);
  119.         }
  120.     }
  121.     
  122.     /**
  123.      * Turns the class on
  124.      * @postcondition isActive()
  125.      */
  126.     public function turnOn () {
  127.         $this->_active = true;
  128.     }
  129.     
  130.     /**
  131.      * Turns the class off
  132.      * @postcondition !isActive()
  133.      */
  134.     public function turnOff () {
  135.         $this->_active = false;
  136.     }
  137.     
  138.     
  139.     
  140.     /** MUTATOR METHODS **/
  141.     /**
  142.      * Sets the Template_Engine object
  143.      * @param Gumbo_Template_Engine $engine 
  144.      */
  145.     protected function setEngine ($engine) {
  146.         $this->_engine = $engine;
  147.     }
  148.     
  149.     /**
  150.      * Sets the standard file (full path)
  151.      * @param string $file 
  152.      * @throws Gumbo_Exception
  153.      */
  154.     public function setFile ($file) {
  155.         try {
  156.             // verify precondition
  157.             if (!is_string ($file)) {
  158.                 throw new Gumbo_Exception ("Invalid Argument 'file:str' => {$file}:" . gettype ($file));
  159.             }
  160.             if (!file_exists ($file)) {
  161.                 throw new Gumbo_Exception ("File Does Not Exist: {$file}");
  162.             }
  163.             
  164.             $this->_file = $file;
  165.         } catch (Gumbo_Exception $e) {
  166.             $e->setFunction (__METHOD__);
  167.             gumbo_trigger ($e);
  168.         }
  169.     }
  170.     
  171.     /**
  172.      * Sets the basic file (full path)
  173.      * @param string|null$file 
  174.      * @throws Gumbo_Exception
  175.      */
  176.     public function setFileBasic ($file) {
  177.         try {
  178.             // verify precondition
  179.             if (!is_null ($file) && !is_string ($file)) {
  180.                 throw new Gumbo_Exception ("Invalid Argument 'file:str|null' => {$file}:" . gettype ($file));
  181.             }
  182.             if (is_string ($file) && !file_exists ($file)) {
  183.                 throw new Gumbo_Exception ("File Does Not Exist: {$file}");
  184.             }
  185.                 
  186.             $this->_file_basic = $file;
  187.         } catch (Gumbo_Exception $e) {
  188.             $e->setFunction (__METHOD__);
  189.             gumbo_trigger ($e);
  190.         }
  191.     }
  192.     
  193.     
  194.     
  195.     /** ACCESSOR METHODS **/
  196.     /**
  197.      * Returns the Special Template's Template_Engine
  198.      * @return Gumbo_Template_Engine 
  199.      */
  200.     protected function getEngine () {
  201.         return $this->_engine;
  202.     }
  203.     
  204.     /**
  205.      * Returns the standard file
  206.      * @return string 
  207.      */
  208.     public function getFile () {
  209.         return $this->_file;
  210.     }
  211.     
  212.     /**
  213.      * Returns the basic file
  214.      * @return string 
  215.      */
  216.     public function getFileBasic () {
  217.         return $this->_file_basic;
  218.     }
  219.     
  220.     /**
  221.      * Returns the Template_Engine element
  222.      * @param string $key 
  223.      * @return Gumbo_Template_Engine 
  224.      * @throws Gumbo_Exception
  225.      */
  226.     public function getElement ($key) {
  227.         try {
  228.             // verify precondition
  229.             if (!is_string ($key)) {
  230.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  231.             }
  232.             if (!isset ($this->_elements [$key])) {
  233.                 throw new Gumbo_Exception ("Invalid Element Key: {$key}");
  234.             }
  235.             
  236.             return $this->_elements [$key];
  237.         } catch (Gumbo_Exception $e) {
  238.             $e->setFunction (__METHOD__);
  239.             gumbo_trigger ($e);
  240.         }
  241.         return null;
  242.     }
  243.     
  244.     /**
  245.      * Returns the list of elements
  246.      * @return Gumbo_Interface_Template_Engine[] 
  247.      */
  248.     public function getElements () {
  249.         return $this->_elements;
  250.     }
  251.     
  252.     /**
  253.      * Returns if the feature is active
  254.      * @return bool 
  255.      */
  256.     public function isActive () {
  257.         return $this->_active;
  258.     }
  259.     
  260. }
  261.  
  262. ?>