5 * This file contains an abstract (PHP 4, so "abstract" is relative)
6 * class meant to define the basic template interface for the
7 * SquirrelMail core application. Subclasses should extend this
8 * class with any custom functionality needed to interface a target
9 * templating engine with SquirrelMail.
11 * @copyright © 2003-2007 The SquirrelMail Project Team
12 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
14 * @package squirrelmail
15 * @subpackage Template
20 /** load template functions */
21 require(SM_PATH
. 'functions/template/general_util.php');
24 * The SquirrelMail Template class.
26 * Basic template class for capturing values and pluging them into a template.
27 * This class uses a similar API to Smarty.
29 * Methods that must be implemented by subclasses are as follows (see method
30 * stubs below for further information about expected behavior):
40 * @author Paul Lesniewski <paul at squirrelmail.org>
41 * @package squirrelmail
53 var $template_set_id = '';
56 * The template set base directory (relative path from
57 * the main SquirrelMail directory (SM_PATH))
62 var $template_dir = '';
65 * The template engine (please use constants defined in constants.php)
70 var $template_engine = '';
73 * The content type for this template set
75 var $content_type = '';
78 * The fall-back template ID
83 var $fallback_template_set_id = '';
86 * The fall-back template directory (relative
87 * path from the main SquirrelMail directory (SM_PATH))
92 var $fallback_template_dir = '';
95 * The fall-back template engine (please use
96 * constants defined in constants.php)
101 var $fallback_template_engine = '';
104 * Template file cache. Structured as an array, whose keys
105 * are all the template file names (with path information relative
106 * to the template set's base directory, e.g., "css/style.css")
107 * found in all parent template sets including the ultimate fall-back
108 * template set. Array values are sub-arrays with the
109 * following key-value pairs:
111 * PATH -- file path, relative to SM_PATH
112 * SET_ID -- the ID of the template set that this file belongs to
113 * ENGINE -- the engine needed to render this template file
116 var $template_file_cache = array();
119 * Extra template engine class objects for rendering templates
120 * that require a different engine than the one for the current
121 * template set. Keys should be the name of the template engine,
122 * values are the corresponding class objects.
127 var $other_template_engine_objects = array();
132 * Please do not call directly. Use Template::construct_template().
134 * @param string $template_set_id the template ID
137 function Template($template_set_id) {
138 //FIXME: find a way to test that this is ONLY ever called
139 // from the construct_template() method (I doubt it
140 // is worth the trouble to parse the current stack trace)
142 // trigger_error('Please do not use default Template() constructor. Instead, use Template::construct_template().', E_USER_ERROR);
144 $this->set_up_template($template_set_id);
151 * This method should always be called instead of trying
152 * to get a Template object from the normal/default constructor,
153 * and is necessary in order to control the return value.
155 * @param string $template_set_id the template ID
157 * @return object The correct Template object for the given template set
162 function construct_template($template_set_id) {
164 $template = new Template($template_set_id);
165 $template->override_plugins();
166 return $template->get_template_engine_subclass();
171 * Set up internal attributes
173 * This method does most of the work for setting up
174 * newly constructed objects.
176 * @param string $template_set_id the template ID
179 function set_up_template($template_set_id) {
181 // FIXME: do we want to place any restrictions on the ID like
182 // making sure no slashes included?
185 $this->template_set_id
= $template_set_id;
188 $this->fallback_template_set_id
= Template
::get_fallback_template_set();
191 // set up template directories
194 = Template
::calculate_template_file_directory($this->template_set_id
);
195 $this->fallback_template_dir
196 = Template
::calculate_template_file_directory($this->fallback_template_set_id
);
199 // determine content type, defaulting to text/html
201 $this->content_type
= Template
::get_template_config($this->template_set_id
,
206 // determine template engine
207 // FIXME: assuming PHP template engine may not necessarily be a good thing
209 $this->template_engine
= Template
::get_template_config($this->template_set_id
,
214 // get template file cache
216 $this->template_file_cache
= Template
::cache_template_file_hierarchy();
221 * Determine what the ultimate fallback template set is.
223 * NOTE that if the fallback setting cannot be found in the
224 * main SquirrelMail configuration settings that the value
225 * of $default is returned.
227 * @param string $default The template set ID to use if
228 * the fallback setting cannot be
229 * found in SM config (optional;
230 * defaults to "default").
232 * @return string The ID of the fallback template set.
237 function get_fallback_template_set($default='default') {
239 // FIXME: do we want to place any restrictions on the ID such as
240 // making sure no slashes included?
242 // values are in main SM config file
244 global $templateset_fallback, $aTemplateSet;
245 $aTemplateSet = (!isset($aTemplateSet) ||
!is_array($aTemplateSet)
246 ?
array() : $aTemplateSet);
247 $templateset_fallback = (!isset($templateset_fallback)
248 ?
$default : $templateset_fallback);
250 // iterate through all template sets, is this a valid skin ID?
253 foreach ($aTemplateSet as $aTemplate) {
254 if ($aTemplate['ID'] === $templateset_fallback) {
261 return $templateset_fallback;
263 // FIXME: note that it is possible for $default to
264 // point to an invalid (nonexistent) template set
265 // and that error will not be caught here
272 * Determine what the default template set is.
274 * NOTE that if the default setting cannot be found in the
275 * main SquirrelMail configuration settings that the value
276 * of $default is returned.
278 * @param string $default The template set ID to use if
279 * the default setting cannot be
280 * found in SM config (optional;
281 * defaults to "default").
283 * @return string The ID of the default template set.
288 function get_default_template_set($default='default') {
290 // FIXME: do we want to place any restrictions on the ID such as
291 // making sure no slashes included?
293 // values are in main SM config file
295 global $templateset_default, $aTemplateSet;
296 $aTemplateSet = (!isset($aTemplateSet) ||
!is_array($aTemplateSet)
297 ?
array() : $aTemplateSet);
298 $templateset_default = (!isset($templateset_default)
299 ?
$default : $templateset_default);
301 // iterate through all template sets, is this a valid skin ID?
304 foreach ($aTemplateSet as $aTemplate) {
305 if ($aTemplate['ID'] === $templateset_default) {
312 return $templateset_default;
314 // FIXME: note that it is possible for $default to
315 // point to an invalid (nonexistent) template set
316 // and that error will not be caught here
323 * Allow template set to override plugin configuration by either
324 * adding or removing plugins.
326 * NOTE: due to when this code executes, plugins activated here
327 * do not have access to the config_override and loading_prefs
328 * hooks; instead, such plugins can use the
329 * "template_plugins_override_after" hook defined below.
332 function override_plugins() {
334 global $disable_plugins, $plugins, $squirrelmail_plugin_hooks, $null;
335 if ($disable_plugins) return;
337 $add_plugins = Template
::get_template_config($this->template_set_id
,
338 'add_plugins', array());
339 $remove_plugins = Template
::get_template_config($this->template_set_id
,
340 'remove_plugins', array());
342 //FIXME (?) we assume $add_plugins and $remove_plugins are arrays -- we could
343 // error check here, or just assume that template authors or admins
344 // won't screw up their config files
347 // disable all plugins? (can still add some by using $add_plugins)
349 if (in_array('*', $remove_plugins)) {
351 $squirrelmail_plugin_hooks = array();
352 $remove_plugins = array();
356 foreach ($add_plugins as $plugin_name) {
357 // add plugin to global plugin array
359 $plugins[] = $plugin_name;
362 // enable plugin -- emulate code from use_plugin() function
363 // in SquirrelMail core, but also need to call the
364 // "squirrelmail_plugin_init_<plugin_name>" function, which
365 // in static configuration is not called (this inconsistency
366 // could be a source of anomalous-seeming bugs in poorly
369 if (file_exists(SM_PATH
. "plugins/$plugin_name/setup.php")) {
370 include_once(SM_PATH
. "plugins/$plugin_name/setup.php");
372 $function = "squirrelmail_plugin_init_$plugin_name";
373 if (function_exists($function))
378 foreach ($remove_plugins as $plugin_name) {
379 // remove plugin from both global plugin & plugin hook arrays
381 $plugin_key = array_search($plugin_name, $plugins);
382 if (!is_null($plugin_key) && $plugin_key !== FALSE) {
383 unset($plugins[$plugin_key]);
384 if (is_array($squirrelmail_plugin_hooks))
385 foreach (array_keys($squirrelmail_plugin_hooks) as $hookName) {
386 unset($squirrelmail_plugin_hooks[$hookName][$plugin_name]);
391 do_hook('template_plugins_override_after', $null);
396 * Instantiate and return correct subclass for this template
397 * set's templating engine.
399 * @param string $template_set_id The template set whose engine
400 * is to be used as an override
401 * (if not given, this template
402 * set's engine is used) (optional).
404 * @return object The Template subclass object for the template engine.
407 function get_template_engine_subclass($template_set_id='') {
409 if (empty($template_set_id)) $template_set_id = $this->template_set_id
;
410 // FIXME: assuming PHP template engine may not necessarily be a good thing
411 $engine = Template
::get_template_config($template_set_id,
412 'template_engine', SQ_PHP_TEMPLATE
);
415 $engine_class_file = SM_PATH
. 'class/template/'
416 . $engine . 'Template.class.php';
418 if (!file_exists($engine_class_file)) {
419 trigger_error('Unknown template engine (' . $engine
420 . ') was specified in template configuration file',
424 $engine_class = $engine . 'Template';
425 require_once($engine_class_file);
426 return new $engine_class($template_set_id);
431 * Determine the relative template directory path for
432 * the given template ID.
434 * @param string $template_set_id The template ID from which to build
437 * @return string The relative template path (based off of SM_PATH)
442 function calculate_template_file_directory($template_set_id) {
444 return 'templates/' . $template_set_id . '/';
449 * Determine the relative images directory path for
450 * the given template ID.
452 * @param string $template_set_id The template ID from which to build
455 * @return string The relative images path (based off of SM_PATH)
460 function calculate_template_images_directory($template_set_id) {
462 return 'templates/' . $template_set_id . '/images/';
467 * Return the relative template directory path for this template set.
469 * @return string The relative path to the template directory based
470 * from the main SquirrelMail directory (SM_PATH).
473 function get_template_file_directory() {
475 return $this->template_dir
;
480 * Return the template ID for the fallback template set.
482 * @return string The ID of the fallback template set.
485 function get_fallback_template_set_id() {
487 return $this->fallback_template_set_id
;
492 * Return the relative template directory path for the
493 * fallback template set.
495 * @return string The relative path to the fallback template
496 * directory based from the main SquirrelMail
497 * directory (SM_PATH).
500 function get_fallback_template_file_directory() {
502 return $this->fallback_template_dir
;
507 * Return the content-type for this template set.
509 * @return string The content-type.
512 function get_content_type() {
514 return $this->content_type
;
519 * Get template set config setting
521 * Given a template set ID and setting name, returns the
522 * setting's value. Note that settings are cached in
523 * session, so "live" changes to template configuration
524 * won't be reflected until the user logs out and back
527 * @param string $template_set_id The template set for which
528 * to look up the setting.
529 * @param string $setting The name of the setting to
531 * @param mixed $default When the requested setting
532 * is not found, the contents
533 * of this value are returned
534 * instead (optional; default
536 * NOTE that unlike sqGetGlobalVar(),
537 * this function will also return
538 * the default value if the
539 * requested setting is found
541 * @param boolean $live_config When TRUE, the target template
542 * set's configuration file is
543 * reloaded every time this
544 * method is called. Default
545 * behavior is to only load the
546 * configuration file if it had
547 * never been loaded before, but
548 * not again after that (optional;
549 * default FALSE). Use with care!
550 * Should mostly be used for
553 * @return mixed The desired setting's value or if not found,
554 * the contents of $default are returned.
559 function get_template_config($template_set_id, $setting,
560 $default=NULL, $live_config=FALSE) {
562 sqGetGlobalVar('template_configuration_settings',
563 $template_configuration_settings,
567 if ($live_config) unset($template_configuration_settings[$template_set_id]);
570 // NOTE: could use isset() instead of empty() below, but
571 // this function is designed to replace empty values
572 // as well as non-existing values with $default
574 if (!empty($template_configuration_settings[$template_set_id][$setting]))
575 return $template_configuration_settings[$template_set_id][$setting];
578 // if template set configuration has been loaded, but this
579 // setting is not known, return $default
581 if (!empty($template_configuration_settings[$template_set_id]))
585 // otherwise (template set configuration has not been loaded before),
586 // load it into session and return the desired setting after that
588 $template_config_file = SM_PATH
589 . Template
::calculate_template_file_directory($template_set_id)
592 if (!file_exists($template_config_file)) {
594 trigger_error('No template configuration file was found where expected: ("'
595 . $template_config_file . '")', E_USER_ERROR
);
599 // we require() the file to let PHP do the variable value
600 // parsing for us, and read the file in manually so we can
601 // know what variable names are used in the config file
602 // (settings can be different depending on specific requirements
603 // of different template engines)... the other way this may
604 // be accomplished is to somehow diff the symbol table
605 // before/after the require(), but anyway, this code should
606 // only run once for this template set...
608 require($template_config_file);
609 $file_contents = implode("\n", file($template_config_file));
612 // note that this assumes no template settings have
613 // a string in them that looks like a variable name like $x
614 // also note that this will attempt to grab things like
615 // $Id found in CVS headers, so we try to adjust for that
616 // by checking that the variable is actually set
618 preg_match_all('/\$(\w+)/', $file_contents, $variables, PREG_PATTERN_ORDER
);
619 foreach ($variables[1] as $variable) {
620 if (isset($
$variable))
621 $template_configuration_settings[$template_set_id][$variable]
625 sqsession_register($template_configuration_settings,
626 'template_configuration_settings');
628 // NOTE: could use isset() instead of empty() below, but
629 // this function is designed to replace empty values
630 // as well as non-existing values with $default
632 if (!empty($template_configuration_settings[$template_set_id][$setting]))
633 return $template_configuration_settings[$template_set_id][$setting];
642 * Obtain template file hierarchy from cache.
644 * If the file hierarchy does not exist in session, it is
645 * constructed and stored in session before being returned
648 * @param boolean $regenerate_cache When TRUE, the file hierarchy
649 * is reloaded and stored fresh
650 * (optional; default FALSE).
651 * @param array $additional_files Must be in same form as the
652 * files in the file hierarchy
653 * cache. These are then added
654 * to the cache (optional; default
655 * empty - no additional files).
657 * @return array Template file hierarchy array, whose keys
658 * are all the template file names (with path
659 * information relative to the template set's
660 * base directory, e.g., "css/style.css")
661 * found in all parent template sets including
662 * the ultimate fall-back template set.
663 * Array values are sub-arrays with the
664 * following key-value pairs:
666 * PATH -- file path, relative to SM_PATH
667 * SET_ID -- the ID of the template set that this file belongs to
668 * ENGINE -- the engine needed to render this template file
673 function cache_template_file_hierarchy($regenerate_cache=FALSE,
674 $additional_files=array()) {
676 sqGetGlobalVar('template_file_hierarchy', $template_file_hierarchy,
677 SQ_SESSION
, array());
680 if ($regenerate_cache) unset($template_file_hierarchy);
682 if (!empty($template_file_hierarchy)) {
684 // have to add additional files if given before returning
686 if (!empty($additional_files)) {
687 $template_file_hierarchy = array_merge($template_file_hierarchy,
689 sqsession_register($template_file_hierarchy,
690 'template_file_hierarchy');
693 return $template_file_hierarchy;
697 // nothing in cache apparently, so go build it now
699 // FIXME: not sure if there is any possibility that
700 // this could be called when $sTemplateID has
701 // yet to be defined... throw error for now,
702 // but if the error occurs, it's a coding error
703 // rather than a configuration error
706 if (empty($sTemplateID)) {
708 trigger_error('Template set ID unknown', E_USER_ERROR
);
712 $template_file_hierarchy = Template
::catalog_template_files($sTemplateID);
714 // additional files, if any
716 if (!empty($additional_files)) {
717 $template_file_hierarchy = array_merge($template_file_hierarchy,
721 sqsession_register($template_file_hierarchy,
722 'template_file_hierarchy');
724 return $template_file_hierarchy;
731 * Traverse template hierarchy and catalogue all template
732 * files (for storing in cache).
734 * Paths to all files in all parent, grand-parent, great grand
735 * parent, etc. template sets (including the fallback template)
736 * are catalogued; for identically named files, the file earlier
737 * in the hierarchy (closest to this template set) is used.
739 * Refuses to traverse directories called ".svn"
741 * @param string $template_set_id The template set in which to
743 * @param array $file_list The file list so far to be added
744 * to (allows recursive behavior)
745 * (optional; default empty array).
746 * @param string $directory The directory in which to search for
747 * files (must be given as full path).
748 * If empty, starts at top-level template
749 * set directory (optional; default empty).
750 * NOTE! Use with care, as behavior is
751 * unpredictable if directory given is not
752 * part of correct template set.
754 * @return mixed The top-level caller will have an array of template
755 * files returned to it; recursive calls to this function
756 * do not receive any return value at all. The format
757 * of the template file array is as described for the
758 * Template class attribute $template_file_cache
763 function catalog_template_files($template_set_id, $file_list=array(), $directory='') {
765 $template_base_dir = SM_PATH
766 . Template
::calculate_template_file_directory($template_set_id);
768 if (empty($directory)) {
769 $directory = $template_base_dir;
773 // bail if we have been asked to traverse a Subversion directory
775 if (strpos($directory, '/.svn') === strlen($directory) - 5) return $file_list;
778 $files_and_dirs = list_files($directory, '', FALSE, TRUE, FALSE, TRUE);
780 // recurse for all the subdirectories in the template set
782 foreach ($files_and_dirs['DIRECTORIES'] as $dir) {
783 $file_list = Template
::catalog_template_files($template_set_id, $file_list, $dir);
786 // place all found files in the cache
787 // FIXME: assuming PHP template engine may not necessarily be a good thing
789 $engine = Template
::get_template_config($template_set_id,
790 'template_engine', SQ_PHP_TEMPLATE
);
791 foreach ($files_and_dirs['FILES'] as $file) {
793 // remove the part of the file path corresponding to the
794 // template set's base directory
796 $relative_file = substr($file, strlen($template_base_dir));
799 * only put file in cache if not already found in earlier template
800 * PATH should be relative to SquirrelMail top directory
802 if (!isset($file_list[$relative_file])) {
803 $file_list[$relative_file] = array(
804 'PATH' => substr($file,strlen(SM_PATH
)),
805 'SET_ID' => $template_set_id,
813 // now if we are currently at the top-level of the template
814 // set base directory, we need to move on to the parent
815 // template set, if any
817 if ($directory == $template_base_dir) {
819 // use fallback when we run out of parents
821 $fallback_id = Template
::get_fallback_template_set();
822 $parent_id = Template
::get_template_config($template_set_id,
823 'parent_template_set',
826 // were we already all the way to the last level? just exit
828 // note that this code allows the fallback set to have
829 // a parent, too, but can result in endless loops
830 // if ($parent_id == $template_set_id) {
832 if ($fallback_id == $template_set_id) {
836 $file_list = Template
::catalog_template_files($parent_id, $file_list);
845 * Look for a template file in a plugin; add to template
846 * file cache if found.
848 * The file is searched for in the following order:
850 * - A directory for the current template set within the plugin:
851 * SM_PATH/plugins/<plugin name>/templates/<template name>/
852 * - In a directory for one of the current template set's ancestor
853 * (inherited) template sets within the plugin:
854 * SM_PATH/plugins/<plugin name>/templates/<parent template name>/
855 * - In a directory for the fallback template set within the plugin:
856 * SM_PATH/plugins/<plugin name>/templates/<fallback template name>/
858 * @param string $plugin The name of the plugin
859 * @param string $file The name of the template file
860 * @param string $template_set_id The ID of the template for which
861 * to start looking for the file
862 * (optional; default is current
865 * @return boolean TRUE if the template file was found, FALSE otherwise.
868 function find_and_cache_plugin_template_file($plugin, $file, $template_set_id='') {
870 if (empty($template_set_id))
871 $template_set_id = $this->template_set_id
;
873 $file_path = SM_PATH
. 'plugins/' . $plugin . '/'
874 . $this->calculate_template_file_directory($template_set_id)
877 if (file_exists($file_path)) {
878 // FIXME: assuming PHP template engine may not necessarily be a good thing
879 $engine = $this->get_template_config($template_set_id,
880 'template_engine', SQ_PHP_TEMPLATE
);
881 $file_list = array('plugins/' . $plugin . '/' . $file => array(
882 'PATH' => substr($file_path, strlen(SM_PATH
)),
883 'SET_ID' => $template_set_id,
887 $this->template_file_cache
888 = $this->cache_template_file_hierarchy(FALSE, $file_list);
893 // not found yet, try parent template set
894 // (use fallback when we run out of parents)
896 $fallback_id = $this->get_fallback_template_set();
897 $parent_id = $this->get_template_config($template_set_id,
898 'parent_template_set',
901 // were we already all the way to the last level? just exit
903 // note that this code allows the fallback set to have
904 // a parent, too, but can result in endless loops
905 // if ($parent_id == $template_set_id) {
907 if ($fallback_id == $template_set_id) {
911 return $this->find_and_cache_plugin_template_file($plugin, $file, $parent_id);
916 * Find the right template file.
918 * The template file is taken from the template file cache, thus
919 * the file is taken from the current template, one of its
920 * ancestors or the fallback template.
922 * Note that it is perfectly acceptable to load template files from
923 * template subdirectories. For example, JavaScript templates found
924 * in the js/ subdirectory would be loaded by passing
925 * "js/<javascript file name>" as the $filename.
927 * Note that the caller can also ask for ALL files in a directory
928 * (and those in the same directory for all ancestor template sets)
929 * by giving a $filename that is a directory name (ending with a
932 * If not found and the file is a plugin template file (indicated
933 * by the presence of "plugins/" on the beginning of $filename),
934 * the target plugin is searched for a substitue template file
935 * before just returning nothing.
937 * Plugin authors must note that the $filename MUST be prefaced
938 * with "plugins/<plugin name>/" in order to correctly resolve the
941 * @param string $filename The name of the template file,
942 * possibly prefaced with
943 * "plugins/<plugin name>/"
944 * indicating that it is a plugin
945 * template, or ending with a
946 * slash, indicating that all files
947 * for that directory name should
949 * @param boolean $directories_ok When TRUE, directory names
950 * are acceptable search values,
951 * and when returning a list of
952 * directory contents, sub-directory
953 * names will also be included
954 * (optional; default FALSE).
955 * NOTE that empty directories
956 * are NOT included in the cache!
957 * @param boolean $directories_only When TRUE, only directory names
958 * are included in the returned
959 * results. (optional; default
960 * FALSE). Setting this argument
961 * to TRUE forces $directories_ok
963 * NOTE that empty directories
964 * are NOT included in the cache!
966 * @return mixed The full path to the template file or a list
967 * of all files in the given directory if $filename
968 * ends with a slash; if not found, an empty string
969 * is returned. The caller is responsible for
970 * throwing errors or other actions if template
974 function get_template_file_path($filename,
975 $directories_ok=FALSE,
976 $directories_only=FALSE) {
978 if ($directories_only) $directories_ok = TRUE;
981 // only looking for directory listing first...
983 // return list of all files in a directory (and that
986 if ($filename{strlen($filename) - 1} == '/') {
988 $return_array = array();
989 foreach ($this->template_file_cache
as $file => $file_info) {
991 // only want files in the requested directory
992 // (AND not in a subdirectory!)
994 if (!$directories_only && strpos($file, $filename) === 0
995 && strpos($file, '/', strlen($filename)) === FALSE)
996 $return_array[] = SM_PATH
. $file_info['PATH'];
998 // directories too? detect by finding any
999 // array key that matches a file in a sub-directory
1000 // of the directory being processed
1002 if ($directories_ok && strpos($file, $filename) === 0
1003 && ($pos = strpos($file, '/', strlen($filename))) !== FALSE
1004 && strpos($file, '/', $pos +
1) === FALSE) {
1005 $directory_name = SM_PATH
1006 . substr($file_info['PATH'],
1008 strrpos($file_info['PATH'], '/'));
1009 if (!in_array($directory_name, $return_array))
1010 $return_array[] = $directory_name;
1014 return $return_array;
1019 // just looking for singular file or directory below...
1021 // figure out what to do with files not found
1023 if ($directories_only ||
empty($this->template_file_cache
[$filename]['PATH'])) {
1025 // if looking for directories...
1026 // have to iterate through cache and detect
1027 // directory by matching any file inside of it
1029 if ($directories_ok) {
1030 foreach ($this->template_file_cache
as $file => $file_info) {
1031 if (strpos($file, $filename) === 0
1032 && ($pos = strpos($file, '/', strlen($filename))) !== FALSE
1033 && strpos($file, '/', $pos +
1) === FALSE) {
1034 return SM_PATH
. substr($file_info['PATH'],
1036 strrpos($file_info['PATH'], '/'));
1040 if ($directories_only) return '';
1043 // plugins get one more chance
1045 if (strpos($filename, 'plugins/') === 0) {
1047 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
1048 $file = substr($filename, strlen($plugin_name) +
9);
1050 if (!$this->find_and_cache_plugin_template_file($plugin_name, $file))
1052 //FIXME: technically I guess we should check for directories
1053 // here too, but that's overkill (no need) presently
1054 // (plugin-provided alternate stylesheet dirs?!? bah.)
1058 // nothing... return empty string (yes, the else is intentional!)
1064 return SM_PATH
. $this->template_file_cache
[$filename]['PATH'];
1069 * Get template engine needed to render given template file.
1071 * If at all possible, just returns a reference to $this, but
1072 * some template files may require a different engine, thus
1073 * an object for that engine (which will subsequently be kept
1074 * in this object for future use) is returned.
1076 * @param string $filename The name of the template file,
1078 * @return object The needed template object to render the template.
1081 function get_rendering_template_engine_object($filename) {
1083 // for files that we cannot find engine info for,
1084 // just return $this
1086 if (empty($this->template_file_cache
[$filename]['ENGINE']))
1090 // otherwise, compare $this' engine to the file's engine
1092 $engine = $this->template_file_cache
[$filename]['ENGINE'];
1093 if ($this->template_engine
== $engine)
1097 // need to load another engine... if already instantiated,
1098 // and stored herein, return that
1099 // FIXME: this assumes same engine setup in all template
1100 // set config files that have same engine in common
1101 // (but keeping a separate class object for every
1102 // template set seems like overkill... for now we
1103 // won't do that unless it becomes a problem)
1105 if (!empty($this->other_template_engine_objects
[$engine])) {
1106 $rendering_engine = $this->other_template_engine_objects
[$engine];
1109 // otherwise, instantiate new engine object, add to cache
1113 $template_set_id = $this->template_file_cache
[$filename]['SET_ID'];
1114 $this->other_template_engine_objects
[$engine]
1115 = $this->get_template_engine_subclass($template_set_id);
1116 $rendering_engine = $this->other_template_engine_objects
[$engine];
1120 // now, need to copy over all the assigned variables
1121 // from $this to the rendering engine (YUCK! -- we need
1122 // to discourage template authors from creating
1123 // situations where engine changes occur)
1125 $rendering_engine->clear_all_assign();
1126 $rendering_engine->assign($this->get_template_vars());
1129 // finally ready to go
1131 return $rendering_engine;
1136 * Return all JavaScript files provided by the template.
1138 * All files found in the template set's "js" directory (and
1139 * that of its ancestors) with the extension ".js" are returned.
1141 * @param boolean $full_path When FALSE, only the file names
1142 * are included in the return array;
1143 * otherwise, path information is
1144 * included (relative to SM_PATH)
1145 * (OPTIONAL; default only file names)
1147 * @return array The required file names/paths.
1150 function get_javascript_includes($full_path=FALSE) {
1152 // since any page from a parent template set
1153 // could end up being loaded, we have to load
1154 // all js files from ancestor template sets,
1155 // not just this set
1157 //$directory = SM_PATH . $this->get_template_file_directory() . 'js';
1158 //$js_files = list_files($directory, '.js', !$full_path);
1160 $js_files = $this->get_template_file_path('js/');
1163 // parse out .js files only
1165 $return_array = array();
1166 foreach ($js_files as $file) {
1168 if (substr($file, strlen($file) - 3) != '.js') continue;
1171 $return_array[] = $file;
1173 $return_array[] = basename($file);
1178 return $return_array;
1183 * Return all alternate stylesheets provided by template.
1185 * All (non-empty) directories found in the template set's
1186 * "css/alternates" directory (and that of its ancestors)
1189 * Note that prettified names are constructed herein by
1190 * taking the directory name, changing underscores to spaces
1191 * and capitalizing each word in the resultant name.
1193 * @param boolean $full_path When FALSE, only the file names
1194 * are included in the return array;
1195 * otherwise, path information is
1196 * included (relative to SM_PATH)
1197 * (OPTIONAL; default only file names)
1199 * @return array A list of the available alternate stylesheets,
1200 * where the keys are the file names (formatted
1201 * according to $full_path) for the stylesheets,
1202 * and the values are the prettified version of
1203 * the file names for display to the user.
1206 function get_alternative_stylesheets($full_path=FALSE) {
1208 // since any page from a parent template set
1209 // could end up being loaded, we will load
1210 // all alternate css files from ancestor
1211 // template sets, not just this set
1213 $css_directories = $this->get_template_file_path('css/alternates/', TRUE, TRUE);
1218 $return_array = array();
1219 foreach ($css_directories as $directory) {
1221 // CVS and SVN directories are not wanted
1223 if ((strpos($directory, '/CVS') === strlen($directory) - 4)
1224 ||
(strpos($directory, '/.svn') === strlen($directory) - 5)) continue;
1226 $pretty_name = ucwords(str_replace('_', ' ', basename($directory)));
1229 $return_array[$directory] = $pretty_name;
1231 $return_array[basename($directory)] = $pretty_name;
1236 return $return_array;
1241 * Return all standard stylsheets provided by the template.
1243 * All files found in the template set's "css" directory (and
1244 * that of its ancestors) with the extension ".css" except
1245 * "rtl.css" (which is dealt with separately) are returned.
1247 * @param boolean $full_path When FALSE, only the file names
1248 * are included in the return array;
1249 * otherwise, path information is
1250 * included (relative to SM_PATH)
1251 * (OPTIONAL; default only file names)
1253 * @return array The required file names/paths.
1256 function get_stylesheets($full_path=FALSE) {
1258 // since any page from a parent template set
1259 // could end up being loaded, we have to load
1260 // all css files from ancestor template sets,
1261 // not just this set
1263 //$directory = SM_PATH . $this->get_template_file_directory() . 'css';
1264 //$css_files = list_files($directory, '.css', !$full_path);
1266 $css_files = $this->get_template_file_path('css/');
1269 // need to leave out "rtl.css"
1271 $return_array = array();
1272 foreach ($css_files as $file) {
1274 if (substr($file, strlen($file) - 4) != '.css') continue;
1275 if (strtolower(basename($file)) == 'rtl.css') continue;
1278 $return_array[] = $file;
1280 $return_array[] = basename($file);
1286 // return sheets for the current template set
1287 // last so we can enable any custom overrides
1288 // of styles in ancestor sheets
1290 return array_reverse($return_array);
1295 * Generate links to all this template set's standard stylesheets
1297 * Subclasses can override this function if stylesheets are
1298 * created differently for the template set's target output
1301 * @return string The stylesheet links as they should be sent
1305 function fetch_standard_stylesheet_links()
1308 $sheets = $this->get_stylesheets(TRUE);
1309 return $this->fetch_external_stylesheet_links($sheets);
1314 * Push out any other stylesheet links as provided (for
1315 * stylesheets not included with the current template set)
1317 * Subclasses can override this function if stylesheets are
1318 * created differently for the template set's target output
1321 * @param mixed $sheets List of the desired stylesheets
1322 * (file path to be used in stylesheet
1323 * href attribute) to output (or single
1324 * stylesheet file path).
1325 FIXME: We could make the incoming array more complex so it can
1326 also contain the other parameters for create_css_link()
1327 such as $name, $alt, $mtype, and $xhtml_end
1330 * @return string The stylesheet links as they should be sent
1334 function fetch_external_stylesheet_links($sheets)
1337 if (!is_array($sheets)) $sheets = array($sheets);
1340 foreach ($sheets as $sheet) {
1341 $output .= create_css_link($sheet);
1349 * Send HTTP header(s) to browser.
1351 * Subclasses can override this function if headers are
1352 * managed differently in the engine's target output
1355 * @param mixed $headers A list of (or a single) header
1359 function header($headers)
1362 if (!is_array($headers)) $headers = array($headers);
1364 foreach ($headers as $header) {
1365 $this->assign('header', $header);
1366 header($this->fetch('header.tpl'));
1372 * Generate a link to the right-to-left stylesheet for
1373 * this template set by getting the "rtl.css" file from
1374 * this template set, its parent (or grandparent, etc.)
1375 * template set, the fall-back template set, or finally,
1376 * fall back to SquirrelMail's own "rtl.css" if need be.
1378 * Subclasses can override this function if stylesheets are
1379 * created differently for the template set's target output
1382 * @return string The stylesheet link as it should be sent
1386 function fetch_right_to_left_stylesheet_link()
1389 // get right template file
1391 $sheet = $this->get_template_file_path('css/rtl.css');
1393 // fall back to SquirrelMail's own default stylesheet
1395 if (empty($sheet)) {
1396 $sheet = SM_PATH
. 'css/rtl.css';
1399 return create_css_link($sheet);
1404 * Display the template
1406 * @param string $file The template file to use
1409 function display($file)
1412 echo $this->fetch($file);
1417 * Applies the template and returns the resultant content string.
1419 * @param string $file The template file to use
1421 * @return string The template contents after applying the given template
1424 function fetch($file) {
1426 // get right template file
1428 $template = $this->get_template_file_path($file);
1431 // special case stylesheet.tpl falls back to SquirrelMail's
1432 // own default stylesheet
1434 if (empty($template) && $file == 'css/stylesheet.tpl') {
1435 $template = SM_PATH
. 'css/default.css';
1439 if (empty($template)) {
1441 trigger_error('The template "' . htmlspecialchars($file)
1442 . '" could not be fetched!', E_USER_ERROR
);
1446 $aPluginOutput = array();
1447 $temp = array(&$aPluginOutput, &$this);
1448 $aPluginOutput = concat_hook_function('template_construct_' . $file,
1450 $this->assign('plugin_output', $aPluginOutput);
1452 //$output = $this->apply_template($template);
1453 $rendering_engine = $this->get_rendering_template_engine_object($file);
1454 $output = $rendering_engine->apply_template($template);
1456 // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
1457 // RESULT IN NOTICABLE PERFORMANCE DEGREDATION. Plugins
1458 // using this hook will probably be rejected by the
1459 // SquirrelMail team.
1461 do_hook('template_output', $output);
1470 * Assigns values to template variables
1472 * Note: this is an abstract method that must be implemented by subclass.
1474 * @param array|string $tpl_var the template variable name(s)
1475 * @param mixed $value the value to assign
1478 function assign($tpl_var, $value = NULL) {
1480 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the assign() method.', E_USER_ERROR
);
1485 * Assigns values to template variables by reference
1487 * Note: this is an abstract method that must be implemented by subclass.
1489 * @param string $tpl_var the template variable name
1490 * @param mixed $value the referenced value to assign
1493 function assign_by_ref($tpl_var, &$value) {
1495 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the assign_by_ref() method.', E_USER_ERROR
);
1500 * Clears the values of all assigned varaiables.
1503 function clear_all_assign() {
1505 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the clear_all_assign() method.', E_USER_ERROR
);
1510 * Returns assigned variable value(s).
1512 * @param string $varname If given, the value of that variable
1513 * is returned, assuming it has been
1514 * previously assigned. If not specified
1515 * an array of all assigned variables is
1516 * returned. (optional)
1518 * @return mixed Desired single variable value or list of all
1519 * assigned variable values.
1522 function get_template_vars($varname=NULL) {
1524 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the get_template_vars() method.', E_USER_ERROR
);
1529 * Appends values to template variables
1531 * Note: this is an abstract method that must be implemented by subclass.
1533 * @param array|string $tpl_var the template variable name(s)
1534 * @param mixed $value the value to append
1535 * @param boolean $merge when $value is given as an array,
1536 * this indicates whether or not that
1537 * array itself should be appended as
1538 * a new template variable value or if
1539 * that array's values should be merged
1540 * into the existing array of template
1544 function append($tpl_var, $value = NULL, $merge = FALSE) {
1546 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the append() method.', E_USER_ERROR
);
1551 * Appends values to template variables by reference
1553 * Note: this is an abstract method that must be implemented by subclass.
1555 * @param string $tpl_var the template variable name
1556 * @param mixed $value the referenced value to append
1557 * @param boolean $merge when $value is given as an array,
1558 * this indicates whether or not that
1559 * array itself should be appended as
1560 * a new template variable value or if
1561 * that array's values should be merged
1562 * into the existing array of template
1566 function append_by_ref($tpl_var, &$value, $merge = FALSE) {
1568 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the append_by_ref() method.', E_USER_ERROR
);
1573 * Applys the template and generates final output destined
1574 * for the user's browser
1576 * Note: this is an abstract method that must be implemented by subclass.
1578 * @param string $filepath The full file path to the template to be applied
1580 * @return string The output for the given template
1583 function apply_template($filepath) {
1585 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the apply_template() method.', E_USER_ERROR
);