class/template/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  * The SquirrelMail (Foowd) template class.
  20  *
  21  * Basic template class for capturing values and pluging them into a template.
  22  * This class uses a similar API to Smarty.
  23  *
  24  * @author Paul James
  25  * @author Monte Ohrt <monte at ispi.net>
  26  * @author Andrei Zmievski <andrei at php.net>
  27  * @package squirrelmail
  28  */
  29 class Template
  30 {
  31   /**
  32    * The templates values array
  33    *
  34    * @var array
  35    */
  36   var $values = array();
  37
  38   /**
  39    * The template directory to use
  40    *
  41    * @var string
  42    */
  43   var $template_dir = '';
  44
  45   /**
  46    * Template files provided by this template set
  47    *
  48    * @var array
  49    */
  50   var $templates_provided = array();
  51
  52   /**
  53    * Javascript files required by the template
  54    *
  55    * @var array
  56    */
  57   var $required_js_files = array();
  58
  59   /**
  60    * Javascript files provided by the template.  If a JS file is required, but
  61    * not provided, the js file by the same name will be included from the
  62    * default template directory.
  63    *
  64    * @var array
  65    */
  66   var $provided_js_files = array();
  67
  68   /**
  69    * Additional stylesheets provided by the template.  This allows template
  70    * authors (namely me to begin with :p) to provide additional CSS sheets
  71    * to templates while using the default template set stylesheet for other
  72    * definitions.
  73    */
  74   var $additional_css_sheets = array();
  75
  76     /**
  77      * Constructor
  78      *
  79      * @param string $sTplDir where the template set is located
  80      */
  81     function Template($sTplDir) {
  82         $this->template_dir = $sTplDir;
  83
  84         // Pull in the tempalte config file
  85         if (!file_exists($this->template_dir . 'template.php')) {
  86              trigger_error('No template.php could be found in the requested template directory ("'.$this->template_dir.'")', E_USER_ERROR);
  87         } else {
  88             include ($this->template_dir . 'template.php');
  89             $this->templates_provided = is_array($templates_provided) ? $templates_provided : array();
  90             $this->required_js_files = is_array($required_js_files) ? $required_js_files : array();
  91             $this->provided_js_files = is_array($provided_js_files) ? $provided_js_files: array();
  92             $this->additional_css_sheets = is_array($additional_css_sheets) ? $additional_css_sheets : array();
  93         }
  94   }
  95
  96
  97   /**
  98    * Assigns values to template variables
  99    *
 100    * @param array|string $tpl_var the template variable name(s)
 101    * @param mixed $value the value to assign
 102    */
 103   function assign($tpl_var, $value = NULL) {
 104     if (is_array($tpl_var))
 105     {
 106       foreach ($tpl_var as $key => $val)
 107       {
 108         if ($key != '')
 109           $this->values[$key] = $val;
 110       }
 111     }
 112     else
 113     {
 114       if ($tpl_var != '')
 115         $this->values[$tpl_var] = $value;
 116     }
 117   }
 118
 119   /**
 120    * Assigns values to template variables by reference
 121    *
 122    * @param string $tpl_var the template variable name
 123    * @param mixed $value the referenced value to assign
 124    */
 125   function assign_by_ref($tpl_var, &$value)
 126   {
 127     if ($tpl_var != '')
 128       $this->values[$tpl_var] = &$value;
 129   }
 130
 131   /**
 132    * Appends values to template variables
 133    *
 134    * @param array|string $tpl_var the template variable name(s)
 135    * @param mixed $value the value to append
 136    */
 137   function append($tpl_var, $value = NULL, $merge = FALSE)
 138   {
 139     if (is_array($tpl_var))
 140     {
 141       foreach ($tpl_var as $_key => $_val)
 142       {
 143         if ($_key != '')
 144         {
 145           if(isset($this->values[$_key]) && !is_array($this->values[$_key]))
 146             settype($this->values[$_key],'array');
 147
 148           if($merge && is_array($_val))
 149           {
 150             foreach($_val as $_mkey => $_mval)
 151               $this->values[$_key][$_mkey] = $_mval;
 152           }
 153           else
 154             $this->values[$_key][] = $_val;
 155         }
 156       }
 157     }
 158     else
 159     {
 160       if ($tpl_var != '' && isset($value))
 161       {
 162         if(isset($this->values[$tpl_var]) && !is_array($this->values[$tpl_var]))
 163           settype($this->values[$tpl_var],'array');
 164
 165         if($merge && is_array($value))
 166         {
 167           foreach($value as $_mkey => $_mval)
 168             $this->values[$tpl_var][$_mkey] = $_mval;
 169         }
 170         else
 171           $this->values[$tpl_var][] = $value;
 172       }
 173     }
 174   }
 175
 176   /**
 177    * Appends values to template variables by reference
 178    *
 179    * @param string $tpl_var the template variable name
 180    * @param mixed $value the referenced value to append
 181    */
 182   function append_by_ref($tpl_var, &$value, $merge = FALSE)
 183   {
 184     if ($tpl_var != '' && isset($value))
 185     {
 186       if(!@is_array($this->values[$tpl_var]))
 187         settype($this->values[$tpl_var],'array');
 188
 189       if ($merge && is_array($value))
 190       {
 191         foreach($value as $_key => $_val)
 192           $this->values[$tpl_var][$_key] = &$value[$_key];
 193       }
 194       else
 195         $this->values[$tpl_var][] = &$value;
 196     }
 197   }
 198
 199   /**
 200    * Display the template
 201    *
 202    * @param string $file The template file to use
 203    */
 204   function display($file)
 205   {
 206     // Pull in our config file
 207     $t = &$this->values; // place values array directly in scope
 208
 209     $template = in_array($file, $this->templates_provided) ? $this->template_dir . $file : SM_PATH .'templates/default/'. $file;
 210     if (!file_exists($template)) {
 211         trigger_error('The template "'.htmlspecialchars($file).'" could not be displayed!', E_USER_ERROR);
 212     } else {
 213         ob_start();
 214         include($template);
 215         ob_end_flush();
 216     }
 217   }
 218
 219   /**
 220    * Return the results of applying a template.
 221    *
 222    * @param string $file The template file to use
 223    * @return string A string of the results
 224    */
 225   function fetch($file) {
 226     $t = &$this->values; // place values array directly in scope
 227
 228     $template = in_array($file, $this->templates_provided) ? $this->template_dir . $file : SM_PATH .'templates/default/'. $file;
 229     if (!file_exists($template)) {
 230         trigger_error('The template "'.htmlspecialchars($file).'" could not be fetched!', E_USER_ERROR);
 231     } else {
 232         ob_start();
 233         include($template);
 234         $contents = ob_get_contents();
 235         ob_end_clean();
 236         return $contents;
 237     }
 238   }
 239
 240   /**
 241    * Return paths to the required javascript files.  Used when generating page
 242    * header.
 243    *
 244    * @return array $paths
 245    */
 246   function getJavascriptIncludes () {
 247     $paths = array();
 248     foreach ($this->required_js_files as $file) {
 249         if (in_array($file, $this->provided_js_files))
 250             $paths[] = './'.$this->template_dir.'js/'.basename($file);
 251         else $paths[] = SM_PATH .'templates/default/js/'.basename($file);
 252     }
 253
 254     return $paths;
 255   }
 256
 257   /**
 258    * Return any additional stylsheets provided by the template.  Used when
 259    * generating page headers.
 260    *
 261    * @return array $paths
 262    */
 263   function getAdditionalStyleSheets () {
 264     $paths = array();
 265     foreach ($this->additional_css_sheets as $css) {
 266         $css = basename($css);
 267         if (strtolower($css) == 'stylesheet.tpl') {
 268             continue;
 269         }
 270         $paths[] = $css;
 271     }
 272     return $paths;
 273   }
 274 }