Changes that follow per the inheritance and associated changes to Template.class.php
[squirrelmail.git] / class / template / Template.class.php
CommitLineData
de4d58cb 1<?php
2
149e4419 3require(SM_PATH . 'functions/template.php');
de4d58cb 4
5/**
6 * Template.class.php
7 *
8 * This file contains an abstract (PHP 4, so "abstract" is relative)
9 * class meant to define the basic template interface for the
10 * SquirrelMail core application. Subclasses should extend this
11 * class with any custom functionality needed to interface a target
12 * templating engine with SquirrelMail.
13 *
14 * @copyright &copy; 2003-2006 The SquirrelMail Project Team
15 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
16 * @version $Id$
17 * @package squirrelmail
18 * @subpackage Template
19 * @since 1.5.2
20 *
21 */
22
23/**
24 * The SquirrelMail Template class.
25 *
26 * Basic template class for capturing values and pluging them into a template.
27 * This class uses a similar API to Smarty.
28 *
29 * Methods that must be implemented by subclasses are as follows (see method
30 * stubs below for further information about expected behavior):
31 *
32 * assign()
33 * assign_by_ref()
d4c2aa24 34 * clear_all_assign()
35 * get_template_vars()
de4d58cb 36 * append()
37 * append_by_ref()
38 * apply_template()
39 *
40 * @author Paul Lesniewski
41 * @package squirrelmail
42 *
43 */
44class Template
45{
46
47 /**
48 * The template ID
49 *
50 * @var string
51 *
52 */
d4c2aa24 53 var $template_set_id = '';
de4d58cb 54
55 /**
d4c2aa24 56 * The template set base directory (relative path from
57 * the main SquirrelMail directory (SM_PATH))
de4d58cb 58 *
59 * @var string
60 *
61 */
62 var $template_dir = '';
63
64 /**
65 * The template engine (please use constants defined in constants.php)
66 *
67 * @var string
68 *
69 */
70 var $template_engine = '';
71
72 /**
d4c2aa24 73 * The fall-back template ID
de4d58cb 74 *
75 * @var string
76 *
77 */
d4c2aa24 78 var $fallback_template_set_id = '';
de4d58cb 79
80 /**
d4c2aa24 81 * The fall-back template directory (relative
82 * path from the main SquirrelMail directory (SM_PATH))
de4d58cb 83 *
84 * @var string
85 *
86 */
d4c2aa24 87 var $fallback_template_dir = '';
de4d58cb 88
89 /**
d4c2aa24 90 * The fall-back template engine (please use
91 * constants defined in constants.php)
de4d58cb 92 *
93 * @var string
94 *
95 */
d4c2aa24 96 var $fallback_template_engine = '';
de4d58cb 97
98 /**
d4c2aa24 99 * Template file cache. Structured as an array, whose keys
100 * are all the template file names (with path information relative
101 * to the template set's base directory, e.g., "css/style.css")
102 * found in all parent template sets including the ultimate fall-back
103 * template set. Array values are sub-arrays with the
104 * following key-value pairs:
de4d58cb 105 *
d4c2aa24 106 * PATH -- file path, relative to SM_PATH
107 * SET_ID -- the ID of the template set that this file belongs to
108 * ENGINE -- the engine needed to render this template file
de4d58cb 109 *
110 */
d4c2aa24 111 var $template_file_cache = array();
de4d58cb 112
113 /**
d4c2aa24 114 * Extra template engine class objects for rendering templates
115 * that require a different engine than the one for the current
116 * template set. Keys should be the name of the template engine,
117 * values are the corresponding class objects.
118 *
119 * @var array
120 *
121 */
122 var $other_template_engine_objects = array();
123
740c26f7 124 /**
de4d58cb 125 * Constructor
126 *
127 * Please do not call directly. Use Template::construct_template().
128 *
d4c2aa24 129 * @param string $template_set_id the template ID
de4d58cb 130 *
131 */
d4c2aa24 132 function Template($template_set_id) {
de4d58cb 133//FIXME: find a way to test that this is ONLY ever called
134// from the construct_template() method (I doubt it
135// is worth the trouble to parse the current stack trace)
136// if (???)
137// trigger_error('Please do not use default Template() constructor. Instead, use Template::construct_template().', E_USER_ERROR);
138
d4c2aa24 139 $this->set_up_template($template_set_id);
de4d58cb 140
141 }
142
143 /**
144 * Construct Template
145 *
146 * This method should always be called instead of trying
147 * to get a Template object from the normal/default constructor,
148 * and is necessary in order to control the return value.
149 *
d4c2aa24 150 * @param string $template_set_id the template ID
de4d58cb 151 *
152 * @return object The correct Template object for the given template set
153 *
d4c2aa24 154 * @static
155 *
de4d58cb 156 */
d4c2aa24 157 function construct_template($template_set_id) {
de4d58cb 158
d4c2aa24 159 $template = new Template($template_set_id);
de4d58cb 160 return $template->get_template_engine_subclass();
161
162 }
163
164 /**
165 * Set up internal attributes
166 *
167 * This method does most of the work for setting up
168 * newly constructed objects.
169 *
d4c2aa24 170 * @param string $template_set_id the template ID
de4d58cb 171 *
172 */
d4c2aa24 173 function set_up_template($template_set_id) {
de4d58cb 174
175 // FIXME: do we want to place any restrictions on the ID like
176 // making sure no slashes included?
177 // get template ID
178 //
d4c2aa24 179 $this->template_set_id = $template_set_id;
de4d58cb 180
181
d4c2aa24 182 $this->fallback_template_set_id = Template::get_fallback_template_set();
de4d58cb 183
184
185 // set up template directories
186 //
187 $this->template_dir
d4c2aa24 188 = Template::calculate_template_file_directory($this->template_set_id);
189 $this->fallback_template_dir
190 = Template::calculate_template_file_directory($this->fallback_template_set_id);
de4d58cb 191
192
d4c2aa24 193 // determine template engine
194 // FIXME: assuming PHP template engine may not necessarily be a good thing
de4d58cb 195 //
d4c2aa24 196 $this->template_engine = Template::get_template_config($this->template_set_id,
197 'template_engine',
198 SQ_PHP_TEMPLATE);
de4d58cb 199
de4d58cb 200
d4c2aa24 201 // get template file cache
202 //
203 $this->template_file_cache = Template::cache_template_file_hierarchy();
de4d58cb 204
d4c2aa24 205 }
de4d58cb 206
d4c2aa24 207 /**
208 * Determine what the ultimate fallback template set is.
209 *
210 * NOTE that if the fallback setting cannot be found in the
211 * main SquirrelMail configuration settings that the value
212 * of $default is returned.
213 *
214 * @param string $default The template set ID to use if
215 * the fallback setting cannot be
216 * found in SM config (optional;
217 * defaults to "default").
218 *
219 * @return string The ID of the fallback template set.
220 *
221 * @static
222 *
223 */
224 function get_fallback_template_set($default='default') {
de4d58cb 225
d4c2aa24 226// FIXME: do we want to place any restrictions on the ID such as
227// making sure no slashes included?
de4d58cb 228
d4c2aa24 229 // values are in main SM config file
de4d58cb 230 //
d4c2aa24 231 global $templateset_fallback, $aTemplateSet;
232 $aTemplateSet = (!isset($aTemplateSet) || !is_array($aTemplateSet)
233 ? array() : $aTemplateSet);
234 $templateset_fallback = (!isset($templateset_fallback)
235 ? 0 : $templateset_fallback);
236
237 return (!empty($aTemplateSet[$templateset_fallback]['ID'])
238 ? $aTemplateSet[$templateset_fallback]['ID'] : $default);
239
240 }
241
242 /**
243 * Determine what the default template set is.
244 *
245 * NOTE that if the default setting cannot be found in the
246 * main SquirrelMail configuration settings that the value
247 * of $default is returned.
248 *
249 * @param string $default The template set ID to use if
250 * the default setting cannot be
251 * found in SM config (optional;
252 * defaults to "default").
253 *
254 * @return string The ID of the default template set.
255 *
256 * @static
257 *
258 */
259 function get_default_template_set($default='default') {
260
261// FIXME: do we want to place any restrictions on the ID such as
262// making sure no slashes included?
263
264 // values are in main SM config file
265 //
266 global $templateset_default, $aTemplateSet;
267 $aTemplateSet = (!isset($aTemplateSet) || !is_array($aTemplateSet)
268 ? array() : $aTemplateSet);
269 $templateset_default = (!isset($templateset_default)
270 ? 0 : $templateset_default);
271
272 return (!empty($aTemplateSet[$templateset_default]['ID'])
273 ? $aTemplateSet[$templateset_default]['ID'] : $default);
de4d58cb 274
275 }
276
277 /**
278 * Instantiate and return correct subclass for this template
279 * set's templating engine.
280 *
d4c2aa24 281 * @param string $template_set_id The template set whose engine
282 * is to be used as an override
283 * (if not given, this template
284 * set's engine is used) (optional).
285 *
de4d58cb 286 * @return object The Template subclass object for the template engine.
287 *
288 */
d4c2aa24 289 function get_template_engine_subclass($template_set_id='') {
290
291 if (empty($template_set_id)) $template_set_id = $this->template_set_id;
292 // FIXME: assuming PHP template engine may not necessarily be a good thing
293 $engine = Template::get_template_config($template_set_id,
294 'template_engine', SQ_PHP_TEMPLATE);
295
de4d58cb 296
297 $engine_class_file = SM_PATH . 'class/template/'
d4c2aa24 298 . $engine . 'Template.class.php';
de4d58cb 299
300 if (!file_exists($engine_class_file)) {
d4c2aa24 301 trigger_error('Unknown template engine (' . $engine
de4d58cb 302 . ') was specified in template configuration file',
303 E_USER_ERROR);
304 }
305
d4c2aa24 306 $engine_class = $engine . 'Template';
307 require_once($engine_class_file);
308 return new $engine_class($template_set_id);
de4d58cb 309
310 }
311
312 /**
313 * Determine the relative template directory path for
314 * the given template ID.
315 *
d4c2aa24 316 * @param string $template_set_id The template ID from which to build
317 * the directory path
de4d58cb 318 *
319 * @return string The relative template path (based off of SM_PATH)
320 *
d4c2aa24 321 * @static
322 *
de4d58cb 323 */
d4c2aa24 324 function calculate_template_file_directory($template_set_id) {
de4d58cb 325
d4c2aa24 326 return 'templates/' . $template_set_id . '/';
de4d58cb 327
328 }
329
330 /**
331 * Determine the relative images directory path for
332 * the given template ID.
333 *
d4c2aa24 334 * @param string $template_set_id The template ID from which to build
335 * the directory path
de4d58cb 336 *
337 * @return string The relative images path (based off of SM_PATH)
338 *
d4c2aa24 339 * @static
340 *
de4d58cb 341 */
d4c2aa24 342 function calculate_template_images_directory($template_set_id) {
de4d58cb 343
d4c2aa24 344 return 'templates/' . $template_set_id . '/images/';
de4d58cb 345
346 }
347
348 /**
349 * Return the relative template directory path for this template set.
350 *
351 * @return string The relative path to the template directory based
352 * from the main SquirrelMail directory (SM_PATH).
353 *
354 */
355 function get_template_file_directory() {
356
357 return $this->template_dir;
358
359 }
360
d4c2aa24 361 /**
362 * Return the template ID for the fallback template set.
363 *
364 * @return string The ID of the fallback template set.
365 *
366 */
367 function get_fallback_template_set_id() {
368
369 return $this->fallback_template_set_id;
370
371 }
de4d58cb 372
373 /**
d4c2aa24 374 * Return the relative template directory path for the
375 * fallback template set.
de4d58cb 376 *
d4c2aa24 377 * @return string The relative path to the fallback template
378 * directory based from the main SquirrelMail
379 * directory (SM_PATH).
380 *
381 */
382 function get_fallback_template_file_directory() {
383
384 return $this->fallback_template_dir;
385
386 }
387
388 /**
389 * Get template set config setting
390 *
391 * Given a template set ID and setting name, returns the
392 * setting's value. Note that settings are cached in
393 * session, so "live" changes to template configuration
394 * won't be reflected until the user logs out and back
395 * in again.
396 *
397 * @param string $template_set_id The template set for which
398 * to look up the setting.
399 * @param string $setting The name of the setting to
400 * retrieve.
401 * @param mixed $default When the requested setting
402 * is not found, the contents
403 * of this value are returned
404 * instead (optional; default
405 * is NULL).
406 * NOTE that unlike sqGetGlobalVar(),
407 * this function will also return
408 * the default value if the
409 * requested setting is found
410 * but is empty.
411 * @param boolean $live_config When TRUE, the target template
412 * set's configuration file is
413 * reloaded every time this
414 * method is called. Default
415 * behavior is to only load the
416 * configuration file if it had
417 * never been loaded before, but
418 * not again after that (optional;
419 * default FALSE). Use with care!
420 * Should mostly be used for
421 * debugging.
422 *
423 * @return mixed The desired setting's value or if not found,
424 * the contents of $default are returned.
425 *
426 * @static
427 *
428 */
429 function get_template_config($template_set_id, $setting,
430 $default=NULL, $live_config=FALSE) {
431
432 sqGetGlobalVar('template_configuration_settings',
433 $template_configuration_settings,
434 SQ_SESSION,
435 array());
436
437 if ($live_config) unset($template_configuration_settings[$template_set_id]);
438
439
440 // NOTE: could use isset() instead of empty() below, but
441 // this function is designed to replace empty values
442 // as well as non-existing values with $default
443 //
444 if (!empty($template_configuration_settings[$template_set_id][$setting]))
445 return $template_configuration_settings[$template_set_id][$setting];
446
447
448 // if template set configuration has been loaded, but this
449 // setting is not known, return $default
450 //
451 if (!empty($template_configuration_settings[$template_set_id]))
452 return $default;
453
454
455 // otherwise (template set configuration has not been loaded before),
456 // load it into session and return the desired setting after that
457 //
458 $template_config_file = SM_PATH
459 . Template::calculate_template_file_directory($template_set_id)
460 . 'config.php';
461
462 if (!file_exists($template_config_file)) {
463
464 trigger_error('No template configuration file was found where expected: ("'
465 . $template_config_file . '")', E_USER_ERROR);
466
467 } else {
468
469 // we require() the file to let PHP do the variable value
470 // parsing for us, and read the file in manually so we can
471 // know what variable names are used in the config file
472 // (settings can be different depending on specific requirements
473 // of different template engines)... the other way this may
474 // be accomplished is to somehow diff the symbol table
475 // before/after the require(), but anyway, this code should
476 // only run once for this template set...
477 //
478 require($template_config_file);
479 $file_contents = implode("\n", file($template_config_file));
480
481
482 // note that this assumes no template settings have
483 // a string in them that looks like a variable name like $x
484 // also note that this will attempt to grab things like
485 // $Id found in CVS headers, so we try to adjust for that
486 // by checking that the variable is actually set
487 //
488 preg_match_all('/\$(\w+)/', $file_contents, $variables, PREG_PATTERN_ORDER);
489 foreach ($variables[1] as $variable) {
490 if (isset($$variable))
491 $template_configuration_settings[$template_set_id][$variable]
492 = $$variable;
493 }
494
495 sqsession_register($template_configuration_settings,
496 'template_configuration_settings');
497
498 // NOTE: could use isset() instead of empty() below, but
499 // this function is designed to replace empty values
500 // as well as non-existing values with $default
501 //
502 if (!empty($template_configuration_settings[$template_set_id][$setting]))
503 return $template_configuration_settings[$template_set_id][$setting];
504 else
505 return $default;
506
507 }
508
509 }
510
511 /**
512 * Obtain template file hierarchy from cache.
513 *
514 * If the file hierarchy does not exist in session, it is
515 * constructed and stored in session before being returned
516 * to the caller.
517 *
518 * @param boolean $regenerate_cache When TRUE, the file hierarchy
519 * is reloaded and stored fresh
520 * (optional; default FALSE).
521 * @param array $additional_files Must be in same form as the
522 * files in the file hierarchy
523 * cache. These are then added
524 * to the cache (optional; default
525 * empty - no additional files).
526 *
527 * @return array Template file hierarchy array, whose keys
528 * are all the template file names (with path
529 * information relative to the template set's
530 * base directory, e.g., "css/style.css")
531 * found in all parent template sets including
532 * the ultimate fall-back template set.
533 * Array values are sub-arrays with the
534 * following key-value pairs:
535 *
536 * PATH -- file path, relative to SM_PATH
537 * SET_ID -- the ID of the template set that this file belongs to
538 * ENGINE -- the engine needed to render this template file
539 *
540 * @static
de4d58cb 541 *
542 */
d4c2aa24 543 function cache_template_file_hierarchy($regenerate_cache=FALSE,
544 $additional_files=array()) {
545
546 sqGetGlobalVar('template_file_hierarchy', $template_file_hierarchy,
547 SQ_SESSION, array());
548
549
550 if ($regenerate_cache) unset($template_file_hierarchy);
551
552
553 if (!empty($template_file_hierarchy)) {
554
555 // have to add additional files if given before returning
556 //
557 if (!empty($additional_files)) {
558 $template_file_hierarchy = array_merge($template_file_hierarchy,
559 $additional_files);
560 sqsession_register($template_file_hierarchy,
561 'template_file_hierarchy');
562 }
563
564 return $template_file_hierarchy;
565 }
566
567
568 // nothing in cache apparently, so go build it now
569 //
570 // FIXME: not sure if there is any possibility that
571 // this could be called when $sTemplateID has
572 // yet to be defined... throw error for now,
573 // but if the error occurs, it's a coding error
574 // rather than a configuration error
575 //
576 global $sTemplateID;
577 if (empty($sTemplateID)) {
578
579 trigger_error('Template set ID unknown', E_USER_ERROR);
580
581 } else {
582
583 $template_file_hierarchy = Template::catalog_template_files($sTemplateID);
584
585 // additional files, if any
586 //
587 if (!empty($additional_files)) {
588 $template_file_hierarchy = array_merge($template_file_hierarchy,
589 $additional_files);
590 }
591
592 sqsession_register($template_file_hierarchy,
593 'template_file_hierarchy');
594
595 return $template_file_hierarchy;
596
597 }
598
599 }
600
601 /**
602 * Traverse template hierarchy and catalogue all template
603 * files (for storing in cache).
604 *
605 * Paths to all files in all parent, grand-parent, great grand
606 * parent, etc. template sets (including the fallback template)
607 * are catalogued; for identically named files, the file earlier
608 * in the hierarchy (closest to this template set) is used.
609 *
610 * @param string $template_set_id The template set in which to
611 * search for files
612 * @param array $file_list The file list so far to be added
613 * to (allows recursive behavior)
614 * (optional; default empty array).
615 * @param string $directory The directory in which to search for
616 * files (must be given as full path).
617 * If empty, starts at top-level template
618 * set directory (optional; default empty).
619 * NOTE! Use with care, as behavior is
620 * unpredictable if directory given is not
621 * part of correct template set.
622 *
623 * @return mixed The top-level caller will have an array of template
624 * files returned to it; recursive calls to this function
625 * do not receive any return value at all. The format
626 * of the template file array is as described for the
627 * Template class attribute $template_file_cache
628 *
629 * @static
630 *
631 */
632 function catalog_template_files($template_set_id, $file_list=array(), $directory='') {
633
634 $template_base_dir = SM_PATH
635 . Template::calculate_template_file_directory($template_set_id);
636
637 if (empty($directory)) {
638 $directory = $template_base_dir;
639 }
640
641 $files_and_dirs = list_files($directory, '', FALSE, TRUE, FALSE, TRUE);
de4d58cb 642
d4c2aa24 643 // recurse for all the subdirectories in the template set
644 //
645 foreach ($files_and_dirs['DIRECTORIES'] as $dir) {
646 $file_list = Template::catalog_template_files($template_set_id, $file_list, $dir);
647 }
648
649 // place all found files in the cache
650 // FIXME: assuming PHP template engine may not necessarily be a good thing
651 //
652 $engine = Template::get_template_config($template_set_id,
653 'template_engine', SQ_PHP_TEMPLATE);
654 foreach ($files_and_dirs['FILES'] as $file) {
655
656 // remove the part of the file path corresponding to the
657 // template set's base directory
658 //
659 $relative_file = substr($file, strlen($template_base_dir));
660
661 // only put file in cache if not already found in earlier template
662 //
663 if (!isset($file_list[$relative_file])) {
664 $file_list[$relative_file] = array(
665 'PATH' => $file,
666 'SET_ID' => $template_set_id,
667 'ENGINE' => $engine,
668 );
669 }
670
671 }
672
673
674 // now if we are currently at the top-level of the template
675 // set base directory, we need to move on to the parent
676 // template set, if any
677 //
678 if ($directory == $template_base_dir) {
679
680 // use fallback when we run out of parents
681 //
682 $fallback_id = Template::get_fallback_template_set();
683 $parent_id = Template::get_template_config($template_set_id,
684 'parent_template_set',
685 $fallback_id);
686
687 // were we already all the way to the last level? just exit
688 //
689 // note that this code allows the fallback set to have
690 // a parent, too, but can result in endless loops
691 // if ($parent_id == $template_set_id) {
692 //
693 if ($fallback_id == $template_set_id) {
694 return $file_list;
695 }
696
697 $file_list = Template::catalog_template_files($parent_id, $file_list);
698
699 }
700
701 return $file_list;
de4d58cb 702
703 }
704
d4c2aa24 705 /**
706 * Look for a template file in a plugin; add to template
707 * file cache if found.
708 *
709 * The file is searched for in the following order:
710 *
711 * - A directory for the current template set within the plugin:
712 * SM_PATH/plugins/<plugin name>/templates/<template name>/
713 * - In a directory for one of the current template set's ancestor
714 * (inherited) template sets within the plugin:
715 * SM_PATH/plugins/<plugin name>/templates/<parent template name>/
716 * - In a directory for the fallback template set within the plugin:
717 * SM_PATH/plugins/<plugin name>/templates/<fallback template name>/
718 *
719 * @param string $plugin The name of the plugin
720 * @param string $file The name of the template file
721 * @param string $template_set_id The ID of the template for which
722 * to start looking for the file
723 * (optional; default is current
724 * template set ID).
725 *
726 * @return boolean TRUE if the template file was found, FALSE otherwise.
727 *
728 */
729 function find_and_cache_plugin_template_file($plugin, $file, $template_set_id='') {
730
731 if (empty($template_set_id))
732 $template_set_id = $this->template_set_id;
733
734 $file_path = SM_PATH . 'plugins/' . $plugin . '/'
735 . $this->calculate_template_file_directory($template_set_id)
736 . $file;
737
738 if (file_exists($file_path)) {
739 // FIXME: assuming PHP template engine may not necessarily be a good thing
740 $engine = $this->get_template_config($template_set_id,
741 'template_engine', SQ_PHP_TEMPLATE);
742 $file_list = array('plugins/' . $plugin . '/' . $file => array(
743 'PATH' => $file_path,
744 'SET_ID' => $template_set_id,
745 'ENGINE' => $engine,
746 )
747 );
748 $this->template_file_cache
749 = $this->cache_template_file_hierarchy(FALSE, $file_list);
750 return TRUE;
751 }
752
753
754 // not found yet, try parent template set
755 // (use fallback when we run out of parents)
756 //
757 $fallback_id = $this->get_fallback_template_set();
758 $parent_id = $this->get_template_config($template_set_id,
759 'parent_template_set',
760 $fallback_id);
761
762 // were we already all the way to the last level? just exit
763 //
764 // note that this code allows the fallback set to have
765 // a parent, too, but can result in endless loops
766 // if ($parent_id == $template_set_id) {
767 //
768 if ($fallback_id == $template_set_id) {
769 return FALSE;
770 }
771
772 return $this->find_and_cache_plugin_template_file($plugin, $file, $parent_id);
773
774 }
de4d58cb 775
776 /**
777 * Find the right template file.
778 *
d4c2aa24 779 * The template file is taken from the template file cache, thus
780 * the file is taken from the current template, one of its
781 * ancestors or the fallback template.
782 *
783 * Note that it is perfectly acceptable to load template files from
784 * template subdirectories. For example, JavaScript templates found
785 * in the js/ subdirectory would be loaded by passing
786 * "js/<javascript file name>" as the $filename.
787 *
788 * Note that the caller can also ask for ALL files in a directory
789 * (and those in the same directory for all ancestor template sets)
790 * by giving a $filename that is a directory name (ending with a
791 * slash).
792 *
793 * If not found and the file is a plugin template file (indicated
794 * by the presence of "plugins/" on the beginning of $filename),
795 * the target plugin is searched for a substitue template file
796 * before just returning nothing.
de4d58cb 797 *
798 * Plugin authors must note that the $filename MUST be prefaced
799 * with "plugins/<plugin name>/" in order to correctly resolve the
800 * template file.
801 *
de4d58cb 802 * @param string $filename The name of the template file,
803 * possibly prefaced with
804 * "plugins/<plugin name>/"
805 * indicating that it is a plugin
d4c2aa24 806 * template, or ending with a
807 * slash, indicating that all files
808 * for that directory name should
809 * be returned.
810 *
811 * @return mixed The full path to the template file or a list
812 * of all files in the given directory if $filename
813 * ends with a slash; if not found, an empty string
814 * is returned. The caller is responsible for
815 * throwing errors or other actions if template
816 * file is not found.
de4d58cb 817 *
818 */
819 function get_template_file_path($filename) {
820
d4c2aa24 821 // return list of all files in a directory (and that
822 // of any ancestors)
de4d58cb 823 //
d4c2aa24 824 if ($filename{strlen($filename) - 1} == '/') {
825
826 $return_array = array();
827 foreach ($this->template_file_cache as $file => $file_info) {
828
829 // only want files in the requested directory
830 // (AND not in a subdirectory!)
831 //
832 if (strpos($file, $filename) === 0
833 && strpos($file, '/', strlen($filename)) === FALSE)
834 $return_array[] = $file_info['PATH'];
de4d58cb 835
d4c2aa24 836 }
837 return $return_array;
838
839 }
840
841 // figure out what to do with files not found
842 //
843 if (empty($this->template_file_cache[$filename]['PATH'])) {
844
845 // plugins get one more chance below; any other
846 // files we just give up now
de4d58cb 847 //
d4c2aa24 848 if (strpos($filename, 'plugins/') !== 0)
849 return '';
de4d58cb 850
d4c2aa24 851 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
852 $file = substr($filename, strlen($plugin_name) + 9);
de4d58cb 853
d4c2aa24 854 if (!$this->find_and_cache_plugin_template_file($plugin_name, $file))
855 return '';
de4d58cb 856
d4c2aa24 857 }
de4d58cb 858
d4c2aa24 859 return $this->template_file_cache[$filename]['PATH'];
de4d58cb 860
d4c2aa24 861 }
de4d58cb 862
d4c2aa24 863 /**
864 * Get template engine needed to render given template file.
865 *
866 * If at all possible, just returns a reference to $this, but
867 * some template files may require a different engine, thus
868 * an object for that engine (which will subsequently be kept
869 * in this object for future use) is returned.
870 *
871 * @param string $filename The name of the template file,
872 *
873 * @return object The needed template object to render the template.
874 *
875 */
876 function get_rendering_template_engine_object($filename) {
877
878 // for files that we cannot find engine info for,
879 // just return $this
880 //
881 if (empty($this->template_file_cache[$filename]['ENGINE']))
882 return $this;
883
884
885 // otherwise, compare $this' engine to the file's engine
886 //
887 $engine = $this->template_file_cache[$filename]['ENGINE'];
888 if ($this->template_engine == $engine)
889 return $this;
890
891
892 // need to load another engine... if already instantiated,
893 // and stored herein, return that
894 // FIXME: this assumes same engine setup in all template
895 // set config files that have same engine in common
896 // (but keeping a separate class object for every
897 // template set seems like overkill... for now we
898 // won't do that unless it becomes a problem)
899 //
900 if (!empty($this->other_template_engine_objects[$engine])) {
901 $rendering_engine = $this->other_template_engine_objects[$engine];
de4d58cb 902
de4d58cb 903
d4c2aa24 904 // otherwise, instantiate new engine object, add to cache
905 // and return it
906 //
907 } else {
908 $template_set_id = $this->template_file_cache[$filename]['SET_ID'];
909 $this->other_template_engine_objects[$engine]
910 = $this->get_template_engine_subclass($template_set_id);
911 $rendering_engine = $this->other_template_engine_objects[$engine];
912 }
de4d58cb 913
de4d58cb 914
d4c2aa24 915 // now, need to copy over all the assigned variables
916 // from $this to the rendering engine (YUCK! -- we need
917 // to discourage template authors from creating
918 // situations where engine changes occur)
919 //
920 $rendering_engine->clear_all_assign();
921 $rendering_engine->assign($this->get_template_vars());
de4d58cb 922
de4d58cb 923
d4c2aa24 924 // finally ready to go
925 //
926 return $rendering_engine;
de4d58cb 927
d4c2aa24 928 }
de4d58cb 929
d4c2aa24 930 /**
931 * Return all JavaScript files provided by the template.
932 *
933 * All files found in the template set's "js" directory (and
934 * that of its ancestors) with the extension ".js" are returned.
935 *
936 * @param boolean $full_path When FALSE, only the file names
937 * are included in the return array;
938 * otherwise, path information is
939 * included (relative to SM_PATH)
940 * (OPTIONAL; default only file names)
941 *
942 * @return array The required file names/paths.
943 *
944 */
945 function get_javascript_includes($full_path=FALSE) {
de4d58cb 946
d4c2aa24 947 // since any page from a parent template set
948 // could end up being loaded, we have to load
949 // all js files from ancestor template sets,
950 // not just this set
951 //
952 //$directory = SM_PATH . $this->get_template_file_directory() . 'js';
953 //$js_files = list_files($directory, '.js', !$full_path);
954 //
955 $js_files = $this->get_template_file_path('js/');
956
957
958 // parse out .js files only
959 //
960 $return_array = array();
961 foreach ($js_files as $file) {
962
963 if (substr($file, strlen($file) - 3) != '.js') continue;
de4d58cb 964
d4c2aa24 965 if ($full_path) {
966 $return_array[] = $file;
967 } else {
968 $return_array[] = basename($file);
de4d58cb 969 }
970
971 }
972
d4c2aa24 973 return $return_array;
de4d58cb 974
975 }
976
977 /**
d4c2aa24 978 * Return all alternate stylesheets provided by template.
979 *
980 * All files found in the template set's "css/alternates"
981 * directory (and that of its ancestors) with the extension
982 * ".css" are returned.
983 *
984 * Note that prettified names are constructed herein by
985 * taking the file name, changing underscores to spaces,
986 * removing the ".css" from the end of the file, and
987 * capitalizing each word in the resultant name.
de4d58cb 988 *
989 * @param boolean $full_path When FALSE, only the file names
990 * are included in the return array;
991 * otherwise, path information is
992 * included (relative to SM_PATH)
993 * (OPTIONAL; default only file names)
994 *
d4c2aa24 995 * @return array A list of the available alternate stylesheets,
996 * where the keys are the file names (formatted
997 * according to $full_path) for the stylesheets,
998 * and the values are the prettified version of
999 * the file names for display to the user.
1000 *
de4d58cb 1001 */
d4c2aa24 1002 function get_alternative_stylesheets($full_path=FALSE) {
de4d58cb 1003
d4c2aa24 1004 // since any page from a parent template set
1005 // could end up being loaded, we will load
1006 // all alternate css files from ancestor
1007 // template sets, not just this set
1008 //
1009 //$directory = SM_PATH . $this->get_template_file_directory() . 'css/alternates';
1010 //$css_files = list_files($directory, '.css', !$full_path);
1011 //
1012 $css_files = $this->get_template_file_path('css/alternates/');
1013
1014
1015 // parse out .css files only
1016 //
1017 $return_array = array();
1018 foreach ($css_files as $file) {
1019
1020 if (substr($file, strlen($file) - 4) != '.css') continue;
1021
1022 $pretty_name = ucwords(str_replace('_', ' ', substr(basename($file), 0, -4)));
1023
1024 if ($full_path) {
1025 $return_array[$file] = $pretty_name;
1026 } else {
1027 $return_array[basename($file)] = $pretty_name;
de4d58cb 1028 }
d4c2aa24 1029
de4d58cb 1030 }
1031
d4c2aa24 1032 return $return_array;
de4d58cb 1033
1034 }
1035
1036 /**
1037 * Return all standard stylsheets provided by the template.
1038 *
d4c2aa24 1039 * All files found in the template set's "css" directory (and
1040 * that of its ancestors) with the extension ".css" except
1041 * "rtl.css" (which is dealt with separately) are returned.
de4d58cb 1042 *
1043 * @param boolean $full_path When FALSE, only the file names
1044 * are included in the return array;
1045 * otherwise, path information is
1046 * included (relative to SM_PATH)
1047 * (OPTIONAL; default only file names)
1048 *
1049 * @return array The required file names/paths.
1050 *
1051 */
1052 function get_stylesheets($full_path=FALSE) {
1053
d4c2aa24 1054 // since any page from a parent template set
1055 // could end up being loaded, we have to load
1056 // all css files from ancestor template sets,
1057 // not just this set
1058 //
1059 //$directory = SM_PATH . $this->get_template_file_directory() . 'css';
1060 //$css_files = list_files($directory, '.css', !$full_path);
1061 //
1062 $css_files = $this->get_template_file_path('css/');
1063
de4d58cb 1064
1065 // need to leave out "rtl.css"
d4c2aa24 1066 //
de4d58cb 1067 $return_array = array();
d4c2aa24 1068 foreach ($css_files as $file) {
de4d58cb 1069
d4c2aa24 1070 if (substr($file, strlen($file) - 4) != '.css') continue;
1071 if (strtolower(basename($file)) == 'rtl.css') continue;
de4d58cb 1072
d4c2aa24 1073 if ($full_path) {
1074 $return_array[] = $file;
1075 } else {
1076 $return_array[] = basename($file);
1077 }
de4d58cb 1078
1079 }
1080
1081 return $return_array;
1082
1083 }
1084
1085 /**
1086 * Generate links to all this template set's standard stylesheets
1087 *
1088 * Subclasses can override this function if stylesheets are
1089 * created differently for the template set's target output
1090 * interface.
1091 *
1092 * @return string The stylesheet links as they should be sent
1093 * to the browser.
1094 *
1095 */
1096 function fetch_standard_stylesheet_links()
1097 {
1098
1099 $sheets = $this->get_stylesheets(TRUE);
1100 return $this->fetch_external_stylesheet_links($sheets);
1101
1102 }
1103
1104 /**
1105 * Push out any other stylesheet links as provided (for
1106 * stylesheets not included with the current template set)
1107 *
1108 * Subclasses can override this function if stylesheets are
1109 * created differently for the template set's target output
1110 * interface.
1111 *
1112 * @param mixed $sheets List of the desired stylesheets
1113 * (file path to be used in stylesheet
1114 * href attribute) to output (or single
1115 * stylesheet file path).
1116FIXME: We could make the incoming array more complex so it can
1117 also contain the other parameters for create_css_link()
1118 such as $name, $alt, $mtype, and $xhtml_end
1119 But do we need to?
1120 *
1121 * @return string The stylesheet links as they should be sent
1122 * to the browser.
1123 *
1124 */
1125 function fetch_external_stylesheet_links($sheets)
1126 {
1127
1128 if (!is_array($sheets)) $sheets = array($sheets);
1129 $output = '';
1130
1131 foreach ($sheets as $sheet) {
1132 $output .= create_css_link($sheet);
1133 }
1134
1135 return $output;
1136
1137 }
1138
1139 /**
1140 * Send HTTP header(s) to browser.
1141 *
1142 * Subclasses can override this function if headers are
1143 * managed differently in the template set's target output
1144 * interface.
1145 *
1146 * @param mixed $headers A list of (or a single) header
1147 * text to be sent.
1148 *
1149 */
1150 function header($headers)
1151 {
1152
1153 if (!is_array($headers)) $headers = array($headers);
1154
1155 foreach ($headers as $header) {
1156 header($header);
1157 }
1158
1159 }
1160
1161 /**
1162 * Generate a link to the right-to-left stylesheet for
d4c2aa24 1163 * this template set by getting the "rtl.css" file from
1164 * this template set, its parent (or grandparent, etc.)
1165 * template set, the fall-back template set, or finally,
1166 * fall back to SquirrelMail's own "rtl.css" if need be.
de4d58cb 1167 *
1168 * Subclasses can override this function if stylesheets are
1169 * created differently for the template set's target output
1170 * interface.
1171 *
1172 * @return string The stylesheet link as it should be sent
1173 * to the browser.
1174 *
1175 */
1176 function fetch_right_to_left_stylesheet_link()
1177 {
1178
1179 // get right template file
1180 //
1181 $sheet = $this->get_template_file_path('css/rtl.css');
1182
1183 // fall back to SquirrelMail's own default stylesheet
1184 //
1185 if (empty($sheet)) {
1186 $sheet = SM_PATH . 'css/rtl.css';
1187 }
1188
1189 return create_css_link($sheet);
1190
1191 }
1192
1193 /**
1194 * Display the template
1195 *
1196 * @param string $file The template file to use
1197 *
1198 */
1199 function display($file)
1200 {
1201
1202 echo $this->fetch($file);
1203
1204 }
1205
1206 /**
1207 * Applies the template and returns the resultant content string.
1208 *
1209 * @param string $file The template file to use
1210 *
1211 * @return string The template contents after applying the given template
1212 *
1213 */
1214 function fetch($file) {
1215
1216 // get right template file
1217 //
1218 $template = $this->get_template_file_path($file);
1219
d4c2aa24 1220
de4d58cb 1221 // special case stylesheet.tpl falls back to SquirrelMail's
1222 // own default stylesheet
1223 //
1224 if (empty($template) && $file == 'css/stylesheet.tpl') {
1225 $template = SM_PATH . 'css/default.css';
1226 }
1227
d4c2aa24 1228
de4d58cb 1229 if (empty($template)) {
1230
1231 trigger_error('The template "' . htmlspecialchars($file)
1232 . '" could not be fetched!', E_USER_ERROR);
1233
1234 } else {
1235
1236 $aPluginOutput = array();
1237 $aPluginOutput = concat_hook_function('template_construct_' . $file,
1238 array($aPluginOutput, $this));
1239 $this->assign('plugin_output', $aPluginOutput);
1240
d4c2aa24 1241 //$output = $this->apply_template($template);
1242 $rendering_engine = $this->get_rendering_template_engine_object($file);
1243 $output = $rendering_engine->apply_template($template);
de4d58cb 1244
1245 // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
1246 // RESULT IN NOTICABLE PERFORMANCE DEGREDATION. Plugins
1247 // using this hook will probably be rejected by the
1248 // SquirrelMail team.
1249 //
1250 $output = filter_hook_function('template_output', $output);
1251
1252 return $output;
1253
1254 }
1255
1256 }
1257
1258 /**
1259 * Assigns values to template variables
1260 *
1261 * Note: this is an abstract method that must be implemented by subclass.
1262 *
1263 * @param array|string $tpl_var the template variable name(s)
1264 * @param mixed $value the value to assign
1265 *
1266 */
1267 function assign($tpl_var, $value = NULL) {
1268
1269 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the assign() method.', E_USER_ERROR);
1270
1271 }
1272
1273 /**
1274 * Assigns values to template variables by reference
1275 *
1276 * Note: this is an abstract method that must be implemented by subclass.
1277 *
1278 * @param string $tpl_var the template variable name
1279 * @param mixed $value the referenced value to assign
1280 *
1281 */
1282 function assign_by_ref($tpl_var, &$value) {
1283
1284 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the assign_by_ref() method.', E_USER_ERROR);
1285
1286 }
1287
1288 /**
d4c2aa24 1289 * Clears the values of all assigned varaiables.
1290 *
1291 */
1292 function clear_all_assign() {
1293
1294 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the clear_all_assign() method.', E_USER_ERROR);
1295
1296 }
1297
1298 /**
1299 * Returns assigned variable value(s).
1300 *
1301 * @param string $varname If given, the value of that variable
1302 * is returned, assuming it has been
1303 * previously assigned. If not specified
1304 * an array of all assigned variables is
1305 * returned. (optional)
1306 *
1307 * @return mixed Desired single variable value or list of all
1308 * assigned variable values.
1309 *
1310 */
1311 function get_template_vars($varname=NULL) {
1312
1313 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the get_template_vars() method.', E_USER_ERROR);
1314
1315 }
1316
1317 /**
de4d58cb 1318 * Appends values to template variables
1319 *
1320 * Note: this is an abstract method that must be implemented by subclass.
1321 *
1322 * @param array|string $tpl_var the template variable name(s)
1323 * @param mixed $value the value to append
1324 * @param boolean $merge when $value is given as an array,
1325 * this indicates whether or not that
1326 * array itself should be appended as
1327 * a new template variable value or if
1328 * that array's values should be merged
1329 * into the existing array of template
1330 * variable values
1331 *
1332 */
1333 function append($tpl_var, $value = NULL, $merge = FALSE) {
1334
1335 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the append() method.', E_USER_ERROR);
1336
1337 }
1338
1339 /**
1340 * Appends values to template variables by reference
1341 *
1342 * Note: this is an abstract method that must be implemented by subclass.
1343 *
1344 * @param string $tpl_var the template variable name
1345 * @param mixed $value the referenced value to append
1346 * @param boolean $merge when $value is given as an array,
1347 * this indicates whether or not that
1348 * array itself should be appended as
1349 * a new template variable value or if
1350 * that array's values should be merged
1351 * into the existing array of template
1352 * variable values
1353 *
1354 */
1355 function append_by_ref($tpl_var, &$value, $merge = FALSE) {
1356
1357 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the append_by_ref() method.', E_USER_ERROR);
1358
1359 }
1360
1361 /**
1362 * Applys the template and generates final output destined
1363 * for the user's browser
1364 *
1365 * Note: this is an abstract method that must be implemented by subclass.
1366 *
1367 * @param string $filepath The full file path to the template to be applied
1368 *
1369 * @return string The output for the given template
1370 *
1371 */
1372 function apply_template($filepath) {
1373
1374 trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the apply_template() method.', E_USER_ERROR);
1375
1376 }
1377
1378}
1379