43547114193fae488c99213d6e9a41df36751e02
[squirrelmail.git] / 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 * The default template directory
47 *
48 * @var string
49 */
50 var $default_template_dir = 'templates/default/';
51
52 /**
53 * Template files provided by this template set
54 *
55 * @var array
56 */
57 var $templates_provided = array();
58
59 /**
60 * Javascript files required by the template
61 *
62 * @var array
63 */
64 var $required_js_files = array();
65
66 /**
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.
70 *
71 * @var array
72 */
73 var $provided_js_files = array();
74
75 /**
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.
79 */
80 var $additional_css_sheets = array();
81
82 /**
83 * Constructor
84 *
85 * @param string $sTplDir where the template set is located
86 */
87 function Template($sTplDir) {
88 $this->template_dir = $sTplDir;
89
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);
93 } else {
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();
99 }
100 }
101
102
103 /**
104 * Assigns values to template variables
105 *
106 * @param array|string $tpl_var the template variable name(s)
107 * @param mixed $value the value to assign
108 */
109 function assign($tpl_var, $value = NULL) {
110 if (is_array($tpl_var))
111 {
112 foreach ($tpl_var as $key => $val)
113 {
114 if ($key != '')
115 $this->values[$key] = $val;
116 }
117 }
118 else
119 {
120 if ($tpl_var != '')
121 $this->values[$tpl_var] = $value;
122 }
123 }
124
125 /**
126 * Assigns values to template variables by reference
127 *
128 * @param string $tpl_var the template variable name
129 * @param mixed $value the referenced value to assign
130 */
131 function assign_by_ref($tpl_var, &$value)
132 {
133 if ($tpl_var != '')
134 $this->values[$tpl_var] = &$value;
135 }
136
137 /**
138 * Appends values to template variables
139 *
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
148 * variable values
149 */
150 function append($tpl_var, $value = NULL, $merge = FALSE)
151 {
152 if (is_array($tpl_var))
153 {
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)
157 {
158 if ($_key != '')
159 {
160 if(isset($this->values[$_key]) && !is_array($this->values[$_key]))
161 settype($this->values[$_key],'array');
162
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))
176 {
177 foreach($_val as $_mkey => $_mval)
178 $this->values[$_key][$_mkey] = $_mval;
179 }
180 else
181 $this->values[$_key][] = $_val;
182 }
183 }
184 }
185 else
186 {
187 if ($tpl_var != '' && isset($value))
188 {
189 if(isset($this->values[$tpl_var]) && !is_array($this->values[$tpl_var]))
190 settype($this->values[$tpl_var],'array');
191
192 if($merge && is_array($value))
193 {
194 foreach($value as $_mkey => $_mval)
195 $this->values[$tpl_var][$_mkey] = $_mval;
196 }
197 else
198 $this->values[$tpl_var][] = $value;
199 }
200 }
201 }
202
203 /**
204 * Appends values to template variables by reference
205 *
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
214 * variable values
215 */
216 function append_by_ref($tpl_var, &$value, $merge = FALSE)
217 {
218 if ($tpl_var != '' && isset($value))
219 {
220 if(!@is_array($this->values[$tpl_var]))
221 settype($this->values[$tpl_var],'array');
222
223 if ($merge && is_array($value))
224 {
225 foreach($value as $_key => $_val)
226 $this->values[$tpl_var][$_key] = &$value[$_key];
227 }
228 else
229 $this->values[$tpl_var][] = &$value;
230 }
231 }
232
233
234 /**
235 *
236 * Return the relative template directory path for this template set.
237 *
238 * @return string The relative path to the template directory based
239 * from the main SquirrelMail directory (SM_PATH).
240 *
241 */
242 function get_template_file_directory() {
243
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;
247
248 }
249
250
251 /**
252 *
253 * Return the relative template directory path for the DEFAULT template set.
254 *
255 * @return string The relative path to the default template directory based
256 * from the main SquirrelMail directory (SM_PATH).
257 *
258 */
259 function get_default_template_file_directory() {
260
261 return $this->default_template_dir;
262
263 }
264
265
266 /**
267 *
268 * Find the right template file.
269 *
270 * Templates are expected to be found in the template set directory,
271 * for example:
272 * SM_PATH/templates/<template name>/
273 * or, in the case of plugin templates, in a plugin directory in the
274 * template set directory, for example:
275 * SM_PATH/templates/<template name>/plugins/<plugin name>/
276 * *OR* in a template directory in the plugin as a fallback, for example:
277 * SM_PATH/plugins/<plugin name>/templates/<template name>/
278 * If the correct file is not found for the current template set, a
279 * default template is loaded, which is expected to be found in the
280 * default template directory, for example:
281 * SM_PATH/templates/default/
282 * or for plugins, in a plugin directory in the default template set,
283 * for example:
284 * SM_PATH/templates/default/plugins/<plugin name>/
285 * *OR* in a default template directory in the plugin as a fallback,
286 * for example:
287 * SM_PATH/plugins/<plugin name>/templates/default/
288 *
289 * Plugin authors must note that the $filename MUST be prefaced
290 * with "plugins/<plugin name>/" in order to correctly resolve the
291 * template file.
292 *
293 * @param string $filename The name of the template file,
294 * possibly prefaced with
295 * "plugins/<plugin name>/"
296 * indicating that it is a plugin
297 * template.
298 *
299 * @return string The full path to the template file; if
300 * not found, an empty string. The caller
301 * is responsible for throwing erros or
302 * other actions if template file is not found.
303 *
304 */
305 function get_template_file_path($filename) {
306
307 // is the template found in the normal template directory?
308 //
309 $filepath = SM_PATH . $this->get_template_file_directory() . $filename;
310 if (!file_exists($filepath)) {
311
312 // no, so now we have to get the default template...
313 // however, in the case of a plugin template, let's
314 // give one more try to find the right template as
315 // provided by the plugin
316 //
317 if (strpos($filename, 'plugins/') === 0) {
318
319 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
320 $filepath = SM_PATH . 'plugins/' . $plugin_name . '/'
321 . $this->get_template_file_directory()
322 . substr($filename, strlen($plugin_name) + 9);
323
324 // no go, we have to get the default template,
325 // first try the default SM template
326 //
327 if (!file_exists($filepath)) {
328
329 $filepath = SM_PATH
330 . $this->get_default_template_file_directory()
331 . $filename;
332
333 // still no luck? get default template from the plugin
334 //
335 if (!file_exists($filepath)) {
336
337 $filepath = SM_PATH . 'plugins/' . $plugin_name . '/'
338 . $this->get_default_template_file_directory()
339 . substr($filename, strlen($plugin_name) + 9);
340
341 // no dice whatsoever, return empty string
342 //
343 if (!file_exists($filepath)) {
344 $filepath = '';
345 }
346
347 }
348
349 }
350
351
352 // get default template for non-plugin templates
353 //
354 } else {
355
356 $filepath = SM_PATH . $this->get_default_template_file_directory()
357 . $filename;
358
359 // no dice whatsoever, return empty string
360 //
361 if (!file_exists($filepath)) {
362 $filepath = '';
363 }
364
365 }
366
367 }
368
369 return $filepath;
370
371 }
372
373
374 /**
375 * Display the template
376 *
377 * @param string $file The template file to use
378 */
379 function display($file)
380 {
381
382 // get right template file
383 //
384 $template = $this->get_template_file_path($file);
385 if (empty($template)) {
386
387 trigger_error('The template "' . htmlspecialchars($file)
388 . '" could not be displayed!', E_USER_ERROR);
389
390 } else {
391
392 $aPluginOutput = array();
393 $aPluginOutput = do_hook_function('template_construct',
394 array($aPluginOutput, $file, $this));
395 $this->assign('plugin_output', $aPluginOutput);
396
397 // pull in our config file ($t? let's try to be more verbose please :-) )
398 //
399 $t = &$this->values; // place values array directly in scope
400
401 ob_start();
402 include($template);
403
404 // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
405 // RESULT IN NOTICABLE PERFORMANCE DEGREDATION. Plugins
406 // using this hook will probably be rejected by the
407 // SquirrelMail team.
408 //
409 // Anyone hooking in here that wants to manipulate the output
410 // buffer has to get the buffer, clean it and then echo the
411 // new buffer like this:
412 // $buffer = ob_get_contents(); ob_clean(); .... echo $new_buffer;
413 //
414 // Don't need to pass buffer contents ourselves
415 // do_hook_function('template_output', array(ob_get_contents()));
416 //
417 do_hook('template_output');
418
419 ob_end_flush();
420
421 }
422 }
423
424 /**
425 * Return the results of applying a template.
426 *
427 * @param string $file The template file to use
428 * @return string A string of the results
429 */
430 function fetch($file) {
431
432 // get right template file
433 //
434 $template = $this->get_template_file_path($file);
435 if (empty($template)) {
436
437 trigger_error('The template "' . htmlspecialchars($file)
438 . '" could not be fetched!', E_USER_ERROR);
439
440 } else {
441
442 $aPluginOutput = array();
443 $aPluginOutput = do_hook_function('template_construct',
444 array($aPluginOutput, $file, $this));
445 $this->assign('plugin_output', $aPluginOutput);
446
447 // pull in our config file ($t? let's try to be more verbose please :-) )
448 //
449 $t = &$this->values; // place values array directly in scope
450
451 ob_start();
452 include($template);
453
454 // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
455 // RESULT IN NOTICABLE PERFORMANCE DEGREDATION. Plugins
456 // using this hook will probably be rejected by the
457 // SquirrelMail team.
458 //
459 // Anyone hooking in here that wants to manipulate the output
460 // buffer has to get the buffer, clean it and then echo the
461 // new buffer like this:
462 // $buffer = ob_get_contents(); ob_clean(); .... echo $new_buffer;
463 //
464 // Don't need to pass buffer contents ourselves
465 // do_hook_function('template_output', array(ob_get_contents()));
466 //
467 do_hook('template_output');
468
469 $contents = ob_get_contents();
470 ob_end_clean();
471 return $contents;
472
473 }
474 }
475
476 /**
477 * Return paths to the required javascript files. Used when generating page
478 * header.
479 *
480 * @return array $paths
481 */
482 function getJavascriptIncludes () {
483 $paths = array();
484 foreach ($this->required_js_files as $file) {
485 if (in_array($file, $this->provided_js_files))
486 $paths[] = './'.$this->template_dir.'js/'.basename($file);
487 else $paths[] = SM_PATH .'templates/default/js/'.basename($file);
488 }
489
490 return $paths;
491 }
492
493 /**
494 * Return any additional stylsheets provided by the template. Used when
495 * generating page headers.
496 *
497 * @return array $paths
498 */
499 function getAdditionalStyleSheets () {
500 $paths = array();
501 foreach ($this->additional_css_sheets as $css) {
502 $css = basename($css);
503 if (strtolower($css) == 'stylesheet.tpl') {
504 continue;
505 }
506 $paths[] = $css;
507 }
508 return $paths;
509 }
510 }