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 2005-2021 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 <paul at squirrelmail.org>
  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 (PHP5 style, required in some future version of PHP)
  44       *
  45       * Please do not call directly.  Use Template::construct_template().
  46       *
  47       * @param string $template_id the template ID
  48       *
  49       */
  50     function __construct($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       * Constructor (PHP4 style, kept for compatibility reasons)
  63       *
  64       * Please do not call directly.  Use Template::construct_template().
  65       *
  66       * @param string $template_id the template ID
  67       *
  68       */
  69     function PHP_Template($template_id) {
  70         self::__construct($template_id);
  71     }
  72
  73     /**
  74       * Assigns values to template variables
  75       *
  76       * @param array|string $tpl_var the template variable name(s)
  77       * @param mixed $value the value to assign
  78 FIXME: Proposed idea to add a parameter here that turns variable
  79        encoding on, so that we can make sure output is always
  80        run through something like sm_encode_html_special_chars() (maybe even nl2br()?)
  81       *
  82       */
  83     function assign($tpl_var, $value = NULL) {
  84
  85         if (is_array($tpl_var))
  86         {
  87             foreach ($tpl_var as $key => $val)
  88             {
  89                 if ($key != '')
  90                 $this->values[$key] = $val;
  91             }
  92         }
  93         else
  94         {
  95             if ($tpl_var != '')
  96             $this->values[$tpl_var] = $value;
  97         }
  98
  99     }
 100
 101     /**
 102       * Assigns values to template variables by reference
 103       *
 104       * @param string $tpl_var the template variable name
 105       * @param mixed $value the referenced value to assign
 106 FIXME: Proposed idea to add a parameter here that turns variable
 107        encoding on, so that we can make sure output is always
 108        run through something like sm_encode_html_special_chars() (maybe even nl2br()?)
 109       *
 110       */
 111     function assign_by_ref($tpl_var, &$value) {
 112
 113         if ($tpl_var != '')
 114             $this->values[$tpl_var] = &$value;
 115
 116     }
 117
 118     /**
 119       * Clears the values of all assigned varaiables.
 120       *
 121       */
 122     function clear_all_assign() {
 123
 124         $this->values = array();
 125
 126     }
 127
 128     /**
 129       * Returns assigned variable value(s).
 130       *
 131       * @param string $varname If given, the value of that variable
 132       *                        is returned, assuming it has been
 133       *                        previously assigned.  If not specified
 134       *                        an array of all assigned variables is
 135       *                        returned. (optional)
 136       *
 137       * @return mixed Desired single variable value or list of all
 138       *               assigned variable values.
 139       *
 140       */
 141     function get_template_vars($varname=NULL) {
 142
 143         // just looking for one value
 144         //
 145         if (!empty($varname)) {
 146             if (!empty($this->values[$varname]))
 147                 return $this->values[$varname];
 148             else
 149 // FIXME: this OK?  What does Smarty do?
 150                 return NULL;
 151         }
 152
 153
 154         // return all variable values
 155         //
 156         return $this->values;
 157
 158     }
 159
 160     /**
 161       * Appends values to template variables
 162       *
 163       * @param array|string $tpl_var the template variable name(s)
 164       * @param mixed $value the value to append
 165       * @param boolean $merge when $value is given as an array,
 166       *                       this indicates whether or not that
 167       *                       array itself should be appended as
 168       *                       a new template variable value or if
 169       *                       that array's values should be merged
 170       *                       into the existing array of template
 171       *                       variable values
 172 FIXME: Proposed idea to add a parameter here that turns variable
 173        encoding on, so that we can make sure output is always
 174        run through something like sm_encode_html_special_chars() (maybe even nl2br()?)
 175       *
 176       */
 177     function append($tpl_var, $value = NULL, $merge = FALSE)
 178     {
 179         if (is_array($tpl_var))
 180         {
 181             foreach ($tpl_var as $_key => $_val)
 182             {
 183                 if ($_key != '')
 184                 {
 185                     if(isset($this->values[$_key]) && !is_array($this->values[$_key]))
 186                         settype($this->values[$_key],'array');
 187
 188                     if($merge && is_array($_val))
 189                     {
 190                         // FIXME: Tentative testing seems to indicate that
 191                         //        this does not mirror Smarty behavior; Smarty
 192                         //        seems to append the full array as a new element
 193                         //        instead of merging, so this behavior is technically
 194                         //        more "correct", but Smarty seems to differ
 195                         foreach($_val as $_mkey => $_mval)
 196                             $this->values[$_key][$_mkey] = $_mval;
 197                     }
 198                     else
 199                         $this->values[$_key][] = $_val;
 200                 }
 201             }
 202         }
 203         else
 204         {
 205             if ($tpl_var != '' && isset($value))
 206             {
 207                 if(isset($this->values[$tpl_var]) && !is_array($this->values[$tpl_var]))
 208                     settype($this->values[$tpl_var],'array');
 209
 210                 if($merge && is_array($value))
 211                 {
 212                     foreach($value as $_mkey => $_mval)
 213                         $this->values[$tpl_var][$_mkey] = $_mval;
 214                 }
 215                 else
 216                     $this->values[$tpl_var][] = $value;
 217             }
 218         }
 219     }
 220
 221     /**
 222       * Appends values to template variables by reference
 223       *
 224       * @param string $tpl_var the template variable name
 225       * @param mixed $value the referenced value to append
 226       * @param boolean $merge when $value is given as an array,
 227       *                       this indicates whether or not that
 228       *                       array itself should be appended as
 229       *                       a new template variable value or if
 230       *                       that array's values should be merged
 231       *                       into the existing array of template
 232       *                       variable values
 233 FIXME: Proposed idea to add a parameter here that turns variable
 234        encoding on, so that we can make sure output is always
 235        run through something like sm_encode_html_special_chars() (maybe even nl2br()?)
 236       *
 237       */
 238     function append_by_ref($tpl_var, &$value, $merge = FALSE)
 239     {
 240         if ($tpl_var != '' && isset($value))
 241         {
 242             if(!@is_array($this->values[$tpl_var]))
 243                 settype($this->values[$tpl_var],'array');
 244
 245             if ($merge && is_array($value))
 246             {
 247                 foreach($value as $_key => $_val)
 248                     $this->values[$tpl_var][$_key] = &$value[$_key];
 249             }
 250             else
 251               $this->values[$tpl_var][] = &$value;
 252         }
 253     }
 254
 255     /**
 256       * Applys the template and generates final output destined
 257       * for the user's browser
 258       *
 259       * @param string $filepath The full file path to the template to be applied
 260       *
 261       * @return string The output for the given template
 262       *
 263       */
 264     function apply_template($filepath) {
 265
 266         // place values array directly in scope
 267         // ($t?  let's try to be more verbose please :-) )
 268         //
 269         $t = &$this->values;
 270
 271         ob_start();
 272         include($filepath);
 273         $contents = ob_get_contents();
 274         ob_end_clean();
 275         return $contents;
 276
 277     }
 278
 279 }
 280