class/template/PHP_Template.class.php

   1 <?php
   2
   3 /**
   4   * Copyright 2003, Paul James
   5   *
   6   * This file contains some methods from the Smarty templating engine version
   7   * 2.5.0 by Monte Ohrt <monte@ispi.net> and Andrei Zmievski <andrei@php.net>.
   8   *
   9   * The SquirrelMail (Foowd) template implementation.
  10   * Derived from the foowd template implementation and adapted
  11   * for squirrelmail
  12   * @copyright &copy; 2005-2006 The SquirrelMail Project Team
  13   * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  14   * @version $Id$
  15   * @package squirrelmail
  16   *
  17   */
  18
  19 /**
  20   * The SquirrelMail PHP Template class.  Extends the base
  21   * Template class for use with PHP template pages.
  22   *
  23   * @author Paul James
  24   * @author Monte Ohrt <monte at ispi.net>
  25   * @author Andrei Zmievski <andrei at php.net>
  26   * @author Paul Lesniewski
  27   * @package squirrelmail
  28   *
  29   */
  30 class PHP_Template extends Template
  31 {
  32
  33     /**
  34       * The templates values array
  35       *
  36       * @var array
  37       *
  38       */
  39     var $values = array();
  40
  41
  42     /**
  43       * Constructor
  44       *
  45       * Please do not call directly.  Use Template::construct_template().
  46       *
  47       * @param string $template_id the template ID
  48       *
  49       */
  50     function PHP_Template($template_id) {
  51 //FIXME: find a way to test that this is ONLY ever called
  52 //       from parent's construct_template() method (I doubt it
  53 //       is worth the trouble to parse the current stack trace)
  54 //        if (???)
  55 //            trigger_error('Please do not use default PHP_Template() constructor.  Instead, use Template::construct_template().', E_USER_ERROR);
  56
  57         parent::Template($template_id);
  58
  59     }
  60
  61     /**
  62       * Assigns values to template variables
  63       *
  64       * @param array|string $tpl_var the template variable name(s)
  65       * @param mixed $value the value to assign
  66 FIXME: Proposed idea to add a parameter here that turns variable
  67        encoding on, so that we can make sure output is always
  68        run through something like htmlspecialchars() (maybe even nl2br()?)
  69       *
  70       */
  71     function assign($tpl_var, $value = NULL) {
  72
  73         if (is_array($tpl_var))
  74         {
  75             foreach ($tpl_var as $key => $val)
  76             {
  77                 if ($key != '')
  78                 $this->values[$key] = $val;
  79             }
  80         }
  81         else
  82         {
  83             if ($tpl_var != '')
  84             $this->values[$tpl_var] = $value;
  85         }
  86
  87     }
  88
  89     /**
  90       * Assigns values to template variables by reference
  91       *
  92       * @param string $tpl_var the template variable name
  93       * @param mixed $value the referenced value to assign
  94 FIXME: Proposed idea to add a parameter here that turns variable
  95        encoding on, so that we can make sure output is always
  96        run through something like htmlspecialchars() (maybe even nl2br()?)
  97       *
  98       */
  99     function assign_by_ref($tpl_var, &$value) {
 100
 101         if ($tpl_var != '')
 102             $this->values[$tpl_var] = &$value;
 103
 104     }
 105
 106     /**
 107       * Clears the values of all assigned varaiables.
 108       *
 109       */
 110     function clear_all_assign() {
 111
 112         $this->values = array();
 113
 114     }
 115
 116     /**
 117       * Returns assigned variable value(s).
 118       *
 119       * @param string $varname If given, the value of that variable
 120       *                        is returned, assuming it has been
 121       *                        previously assigned.  If not specified
 122       *                        an array of all assigned variables is
 123       *                        returned. (optional)
 124       *
 125       * @return mixed Desired single variable value or list of all
 126       *               assigned variable values.
 127       *
 128       */
 129     function get_template_vars($varname=NULL) {
 130
 131         // just looking for one value
 132         //
 133         if (!empty($varname)) {
 134             if (!empty($this->values[$varname]))
 135                 return $this->values[$varname];
 136             else
 137 // FIXME: this OK?  What does Smarty do?
 138                 return NULL;
 139         }
 140
 141
 142         // return all variable values
 143         //
 144         return $this->values;
 145
 146     }
 147
 148     /**
 149       * Appends values to template variables
 150       *
 151       * @param array|string $tpl_var the template variable name(s)
 152       * @param mixed $value the value to append
 153       * @param boolean $merge when $value is given as an array,
 154       *                       this indicates whether or not that
 155       *                       array itself should be appended as
 156       *                       a new template variable value or if
 157       *                       that array's values should be merged
 158       *                       into the existing array of template
 159       *                       variable values
 160 FIXME: Proposed idea to add a parameter here that turns variable
 161        encoding on, so that we can make sure output is always
 162        run through something like htmlspecialchars() (maybe even nl2br()?)
 163       *
 164       */
 165     function append($tpl_var, $value = NULL, $merge = FALSE)
 166     {
 167         if (is_array($tpl_var))
 168         {
 169             foreach ($tpl_var as $_key => $_val)
 170             {
 171                 if ($_key != '')
 172                 {
 173                     if(isset($this->values[$_key]) && !is_array($this->values[$_key]))
 174                         settype($this->values[$_key],'array');
 175
 176                     if($merge && is_array($_val))
 177                     {
 178                         // FIXME: Tentative testing seems to indicate that
 179                         //        this does not mirror Smarty behavior; Smarty
 180                         //        seems to append the full array as a new element
 181                         //        instead of merging, so this behavior is technically
 182                         //        more "correct", but Smarty seems to differ
 183                         foreach($_val as $_mkey => $_mval)
 184                             $this->values[$_key][$_mkey] = $_mval;
 185                     }
 186                     else
 187                         $this->values[$_key][] = $_val;
 188                 }
 189             }
 190         }
 191         else
 192         {
 193             if ($tpl_var != '' && isset($value))
 194             {
 195                 if(isset($this->values[$tpl_var]) && !is_array($this->values[$tpl_var]))
 196                     settype($this->values[$tpl_var],'array');
 197
 198                 if($merge && is_array($value))
 199                 {
 200                     foreach($value as $_mkey => $_mval)
 201                         $this->values[$tpl_var][$_mkey] = $_mval;
 202                 }
 203                 else
 204                     $this->values[$tpl_var][] = $value;
 205             }
 206         }
 207     }
 208
 209     /**
 210       * Appends values to template variables by reference
 211       *
 212       * @param string $tpl_var the template variable name
 213       * @param mixed $value the referenced value to append
 214       * @param boolean $merge when $value is given as an array,
 215       *                       this indicates whether or not that
 216       *                       array itself should be appended as
 217       *                       a new template variable value or if
 218       *                       that array's values should be merged
 219       *                       into the existing array of template
 220       *                       variable values
 221 FIXME: Proposed idea to add a parameter here that turns variable
 222        encoding on, so that we can make sure output is always
 223        run through something like htmlspecialchars() (maybe even nl2br()?)
 224       *
 225       */
 226     function append_by_ref($tpl_var, &$value, $merge = FALSE)
 227     {
 228         if ($tpl_var != '' && isset($value))
 229         {
 230             if(!@is_array($this->values[$tpl_var]))
 231                 settype($this->values[$tpl_var],'array');
 232
 233             if ($merge && is_array($value))
 234             {
 235                 foreach($value as $_key => $_val)
 236                     $this->values[$tpl_var][$_key] = &$value[$_key];
 237             }
 238             else
 239               $this->values[$tpl_var][] = &$value;
 240         }
 241     }
 242
 243     /**
 244       * Applys the template and generates final output destined
 245       * for the user's browser
 246       *
 247       * @param string $filepath The full file path to the template to be applied
 248       *
 249       * @return string The output for the given template
 250       *
 251       */
 252     function apply_template($filepath) {
 253
 254         // place values array directly in scope
 255         // ($t?  let's try to be more verbose please :-) )
 256         //
 257         $t = &$this->values;
 258
 259         ob_start();
 260         include($filepath);
 261         $contents = ob_get_contents();
 262         ob_end_clean();
 263         return $contents;
 264
 265     }
 266
 267 }
 268