bf2dcc3fd51a35f21dad2b89dc475eb8dd82b180
4 * Copyright 2003, Paul James
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>.
9 * The SquirrelMail (Foowd) template implementation.
10 * Derived from the foowd template implementation and adapted
12 * @copyright © 2005-2006 The SquirrelMail Project Team
13 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
15 * @package squirrelmail
19 * The SquirrelMail (Foowd) template class.
21 * Basic template class for capturing values and pluging them into a template.
22 * This class uses a similar API to Smarty.
25 * @author Monte Ohrt <monte at ispi.net>
26 * @author Andrei Zmievski <andrei at php.net>
27 * @package squirrelmail
32 * The templates values array
36 var $values = array();
39 * The template directory to use
43 var $template_dir = '';
46 * The default template directory
50 var $default_template_dir = 'templates/default/';
53 * Template files provided by this template set
57 var $templates_provided = array();
60 * Javascript files required by the template
64 var $required_js_files = array();
67 * Javascript files provided by the template. If a JS file is required, but
68 * not provided, the js file by the same name will be included from the
69 * default template directory.
73 var $provided_js_files = array();
76 * Additional stylesheets provided by the template. This allows template
77 * authors to provide additional CSS sheets to templates while using the
78 * default template set stylesheet for other definitions.
80 var $additional_css_sheets = array();
85 * @param string $sTplDir where the template set is located
87 function Template($sTplDir) {
88 $this->template_dir
= $sTplDir;
90 // Pull in the tempalte config file
91 if (!file_exists($this->template_dir
. 'template.php')) {
92 trigger_error('No template.php could be found in the requested template directory ("'.$this->template_dir
.'")', E_USER_ERROR
);
94 include ($this->template_dir
. 'template.php');
95 $this->templates_provided
= is_array($templates_provided) ?
$templates_provided : array();
96 $this->required_js_files
= is_array($required_js_files) ?
$required_js_files : array();
97 $this->provided_js_files
= is_array($provided_js_files) ?
$provided_js_files: array();
98 $this->additional_css_sheets
= is_array($additional_css_sheets) ?
$additional_css_sheets : array();
104 * Assigns values to template variables
106 * @param array|string $tpl_var the template variable name(s)
107 * @param mixed $value the value to assign
109 function assign($tpl_var, $value = NULL) {
110 if (is_array($tpl_var))
112 foreach ($tpl_var as $key => $val)
115 $this->values
[$key] = $val;
121 $this->values
[$tpl_var] = $value;
126 * Assigns values to template variables by reference
128 * @param string $tpl_var the template variable name
129 * @param mixed $value the referenced value to assign
131 function assign_by_ref($tpl_var, &$value)
134 $this->values
[$tpl_var] = &$value;
138 * Appends values to template variables
140 * @param array|string $tpl_var the template variable name(s)
141 * @param mixed $value the value to append
142 * @param boolean $merge when $value is given as an array,
143 * this indicates whether or not that
144 * array itself should be appended as
145 * a new template variable value or if
146 * that array's values should be merged
147 * into the existing array of template
150 function append($tpl_var, $value = NULL, $merge = FALSE)
152 if (is_array($tpl_var))
154 //FIXME: $tpl_var is supposed to be a list of template var names,
155 // so we should be looking at the values NOT the keys!
156 foreach ($tpl_var as $_key => $_val)
160 if(isset($this->values
[$_key]) && !is_array($this->values
[$_key]))
161 settype($this->values
[$_key],'array');
163 //FIXME: we should be iterating the $value array here not the values of the
164 // list of template variable names! I think this is totally broken
165 // This might just be a matter of needing to clarify the method's API;
166 // values may have been meant to be passed in $tpl_var in the case that
167 // $tpl_var is an array. Ugly and non-intuitive.
168 // PROPOSAL: API should be as such:
169 // if (is_string($tpl_var)) then $values are added/merged as already done
170 // if (is_array($tpl_var)) then $values is required to be an array whose
171 // keys must match up with $tpl_var keys and
172 // whose values are then what is added to
173 // each template variable value (array or
174 // strings, doesn't matter)
175 if($merge && is_array($_val))
177 foreach($_val as $_mkey => $_mval)
178 $this->values
[$_key][$_mkey] = $_mval;
181 $this->values
[$_key][] = $_val;
187 if ($tpl_var != '' && isset($value))
189 if(isset($this->values
[$tpl_var]) && !is_array($this->values
[$tpl_var]))
190 settype($this->values
[$tpl_var],'array');
192 if($merge && is_array($value))
194 foreach($value as $_mkey => $_mval)
195 $this->values
[$tpl_var][$_mkey] = $_mval;
198 $this->values
[$tpl_var][] = $value;
204 * Appends values to template variables by reference
206 * @param string $tpl_var the template variable name
207 * @param mixed $value the referenced value to append
208 * @param boolean $merge when $value is given as an array,
209 * this indicates whether or not that
210 * array itself should be appended as
211 * a new template variable value or if
212 * that array's values should be merged
213 * into the existing array of template
216 function append_by_ref($tpl_var, &$value, $merge = FALSE)
218 if ($tpl_var != '' && isset($value))
220 if(!@is_array
($this->values
[$tpl_var]))
221 settype($this->values
[$tpl_var],'array');
223 if ($merge && is_array($value))
225 foreach($value as $_key => $_val)
226 $this->values
[$tpl_var][$_key] = &$value[$_key];
229 $this->values
[$tpl_var][] = &$value;
236 * Return the relative template directory path for this template set.
238 * @return string The relative path to the template directory based
239 * from the main SquirrelMail directory (SM_PATH).
242 function get_template_file_directory() {
244 //FIXME: temporarily parse off SM_PATH from the template dir class attribute until we can change the entire template subsystem such that the template dir is derived internally in this class from the template ID/name/attributes
245 return substr($this->template_dir
, strlen(SM_PATH
));
246 return $this->template_dir
;
253 * Return the relative template directory path for the DEFAULT template set.
255 * @return string The relative path to the default template directory based
256 * from the main SquirrelMail directory (SM_PATH).
259 function get_default_template_file_directory() {
261 return $this->default_template_dir
;
268 * Find the right template file.
270 * Templates are expected to be found in the template set directory
271 * (for example SM_PATH/templates/<template name>/) or, in the case
272 * of plugin templates, in a plugin directory in the template set
273 * directory (for example,
274 * SM_PATH/templates/<template name>/plugins/<plugin name>/) *OR* in
275 * a template directory in the plugin as a fallback (for example,
276 * SM_PATH/plugins/<plugin name>/templates/<template name>/). If
277 * the correct file is not found for the current template set, a
278 * default template is loaded, which is expected to be found in the
279 * default template directory (for example, SM_PATH/templates/default/)
280 * or for plugins, in a plugin directory in the default template set
281 * (for example, SM_PATH/templates/default/plugins/<plugin name>/),
282 * *OR* in a default template directory in the plugin as a fallback
283 * (for example, SM_PATH/plugins/<plugin name>/templates/default/).
285 * @param string $filename The name of the template file,
286 * possibly prefaced with
287 * "plugins/<plugin name>/"
288 * indicating that it is a plugin
291 * @return string The full path to the template file; if
292 * not found, an empty string. The caller
293 * is responsible for throwing erros or
294 * other actions if template file is not found.
297 function get_template_file_path($filename) {
299 // is the template found in the normal template directory?
301 $filepath = SM_PATH
. $this->get_template_file_directory() . $filename;
302 if (!file_exists($filepath)) {
304 // no, so now we have to get the default template...
305 // however, in the case of a plugin template, let's
306 // give one more try to find the right template as
307 // provided by the plugin
309 if (strpos($filename, 'plugins/') === 0) {
311 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
312 $filepath = SM_PATH
. 'plugins/' . $plugin_name . '/'
313 . $this->get_template_file_directory()
314 . substr($filename, strlen($plugin_name) +
9);
316 // no go, we have to get the default template
319 if (!file_exists($filepath)) {
321 $filepath = SM_PATH
. 'plugins/' . $plugin_name . '/'
322 . $this->get_default_template_file_directory()
323 . substr($filename, strlen($plugin_name) +
9);
325 // no dice whatsoever, return empty string
327 if (!file_exists($filepath)) {
334 // get default template for non-plugin templates
338 $filepath = SM_PATH
. $this->get_default_template_file_directory()
341 // no dice whatsoever, return empty string
343 if (!file_exists($filepath)) {
357 * Display the template
359 * @param string $file The template file to use
361 function display($file)
363 // Pull in our config file
364 $t = &$this->values
; // place values array directly in scope
366 // Get right template file
367 $template = $this->get_template_file_path($file);
368 if (empty($template)) {
369 trigger_error('The template "'.htmlspecialchars($file).'" could not be displayed!', E_USER_ERROR
);
378 * Return the results of applying a template.
380 * @param string $file The template file to use
381 * @return string A string of the results
383 function fetch($file) {
384 $t = &$this->values
; // place values array directly in scope
386 // Get right template file
387 $template = $this->get_template_file_path($file);
388 if (!file_exists($template)) {
389 trigger_error('The template "'.htmlspecialchars($file).'" could not be fetched!', E_USER_ERROR
);
393 $contents = ob_get_contents();
400 * Return paths to the required javascript files. Used when generating page
403 * @return array $paths
405 function getJavascriptIncludes () {
407 foreach ($this->required_js_files
as $file) {
408 if (in_array($file, $this->provided_js_files
))
409 $paths[] = './'.$this->template_dir
.'js/'.basename($file);
410 else $paths[] = SM_PATH
.'templates/default/js/'.basename($file);
417 * Return any additional stylsheets provided by the template. Used when
418 * generating page headers.
420 * @return array $paths
422 function getAdditionalStyleSheets () {
424 foreach ($this->additional_css_sheets
as $css) {
425 $css = basename($css);
426 if (strtolower($css) == 'stylesheet.tpl') {