3 require(SM_PATH
. 'functions/template_functions.php');
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.
14 * @copyright © 2003-2006 The SquirrelMail Project Team
15 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
17 * @package squirrelmail
18 * @subpackage Template
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):
38 * @author Paul Lesniewski
39 * @package squirrelmail
51 var $template_id = '';
54 * The template directory to use
59 var $template_dir = '';
62 * The template engine (please use constants defined in constants.php)
67 var $template_engine = '';
70 * The default template ID
75 var $default_template_id = '';
78 * The default template directory
83 var $default_template_dir = '';
86 * The default template engine (please use constants defined in constants.php)
91 var $default_template_engine = '';
94 * Javascript files required by the template
99 var $required_js_files = array();
104 * Please do not call directly. Use Template::construct_template().
106 * @param string $template_id the template ID
109 function Template($template_id) {
110 //FIXME: find a way to test that this is ONLY ever called
111 // from the construct_template() method (I doubt it
112 // is worth the trouble to parse the current stack trace)
114 // trigger_error('Please do not use default Template() constructor. Instead, use Template::construct_template().', E_USER_ERROR);
116 $this->set_up_template($template_id);
123 * This method should always be called instead of trying
124 * to get a Template object from the normal/default constructor,
125 * and is necessary in order to control the return value.
127 * @param string $template_id the template ID
129 * @return object The correct Template object for the given template set
132 function construct_template($template_id) {
134 $template = new Template($template_id);
135 return $template->get_template_engine_subclass();
140 * Set up internal attributes
142 * This method does most of the work for setting up
143 * newly constructed objects.
145 * @param string $template_id the template ID
148 function set_up_template($template_id) {
150 // FIXME: do we want to place any restrictions on the ID like
151 // making sure no slashes included?
154 $this->template_id
= $template_id;
157 // FIXME: do we want to place any restrictions on the ID like
158 // making sure no slashes included?
159 // get default template ID
161 global $templateset_default, $aTemplateSet;
162 $aTemplateSet = (!isset($aTemplateSet) ||
!is_array($aTemplateSet)
163 ?
array() : $aTemplateSet);
164 $templateset_default = (!isset($templateset_default) ?
0 : $templateset_default);
165 $this->default_template_id
= (!empty($aTemplateSet[$templateset_default]['ID'])
166 ?
$aTemplateSet[$templateset_default]['ID']
170 // set up template directories
173 = Template
::calculate_template_file_directory($this->template_id
);
174 $this->default_template_dir
175 = Template
::calculate_template_file_directory($this->default_template_id
);
178 // pull in the template config file and load javascript and
179 // css files needed for this template set
181 $template_config_file = SM_PATH
. $this->get_template_file_directory()
183 if (!file_exists($template_config_file)) {
185 trigger_error('No template configuration file was found where expected: ("'
186 . $template_config_file . '")', E_USER_ERROR
);
190 require($template_config_file);
191 $this->required_js_files
= is_array($required_js_files)
192 ?
$required_js_files : array();
197 // determine template engine
199 if (empty($template_engine)) {
200 trigger_error('No template engine ($template_engine) was specified in template configuration file: ("'
201 . $template_config_file . '")', E_USER_ERROR
);
203 $this->template_engine
= $template_engine;
209 * Instantiate and return correct subclass for this template
210 * set's templating engine.
212 * @return object The Template subclass object for the template engine.
215 function get_template_engine_subclass() {
217 $engine_class_file = SM_PATH
. 'class/template/'
218 . $this->template_engine
. 'Template.class.php';
220 if (!file_exists($engine_class_file)) {
221 trigger_error('Unknown template engine (' . $this->template_engine
222 . ') was specified in template configuration file',
226 $engine_class = $this->template_engine
. 'Template';
227 require($engine_class_file);
228 return new $engine_class($this->template_id
);
233 * Determine the relative template directory path for
234 * the given template ID.
236 * @param string $template_id The template ID from which to build
239 * @return string The relative template path (based off of SM_PATH)
242 function calculate_template_file_directory($template_id) {
244 return 'templates/' . $template_id . '/';
249 * Determine the relative images directory path for
250 * the given template ID.
252 * @param string $template_id The template ID from which to build
255 * @return string The relative images path (based off of SM_PATH)
258 function calculate_template_images_directory($template_id) {
260 return 'templates/' . $template_id . '/images/';
265 * Return the relative template directory path for this template set.
267 * @return string The relative path to the template directory based
268 * from the main SquirrelMail directory (SM_PATH).
271 function get_template_file_directory() {
273 return $this->template_dir
;
279 * Return the relative template directory path for the DEFAULT template set.
281 * @return string The relative path to the default template directory based
282 * from the main SquirrelMail directory (SM_PATH).
285 function get_default_template_file_directory() {
287 return $this->default_template_dir
;
293 * Find the right template file.
295 * Templates are expected to be found in the template set directory,
297 * SM_PATH/templates/<template name>/
298 * or, in the case of plugin templates, in a plugin directory in the
299 * template set directory, for example:
300 * SM_PATH/templates/<template name>/plugins/<plugin name>/
301 * *OR* in a template directory in the plugin as a fallback, for example:
302 * SM_PATH/plugins/<plugin name>/templates/<template name>/
303 * If the correct file is not found for the current template set, a
304 * default template is loaded, which is expected to be found in the
305 * default template directory, for example:
306 * SM_PATH/templates/<default template>/
307 * or for plugins, in a plugin directory in the default template set,
309 * SM_PATH/templates/<default template>/plugins/<plugin name>/
310 * *OR* in a default template directory in the plugin as a fallback,
312 * SM_PATH/plugins/<plugin name>/templates/<default template>/
313 * *OR* if the plugin template still cannot be found, one last attempt
314 * will be made to load it from a hard-coded default template directory
316 * SM_PATH/plugins/<plugin name>/templates/default/
318 * Plugin authors must note that the $filename MUST be prefaced
319 * with "plugins/<plugin name>/" in order to correctly resolve the
322 * Note that it is perfectly acceptable to load template files from
323 * template subdirectories other than plugins; for example, JavaScript
324 * templates found in the js/ subdirectory would be loaded by passing
325 * "js/<javascript file name>" as the $filename.
327 * @param string $filename The name of the template file,
328 * possibly prefaced with
329 * "plugins/<plugin name>/"
330 * indicating that it is a plugin
333 * @return string The full path to the template file; if
334 * not found, an empty string. The caller
335 * is responsible for throwing erros or
336 * other actions if template file is not found.
339 function get_template_file_path($filename) {
341 // is the template found in the normal template directory?
343 $filepath = SM_PATH
. $this->get_template_file_directory() . $filename;
344 if (!file_exists($filepath)) {
346 // no, so now we have to get the default template...
347 // however, in the case of a plugin template, let's
348 // give one more try to find the right template as
349 // provided by the plugin
351 if (strpos($filename, 'plugins/') === 0) {
353 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
354 $filepath = SM_PATH
. 'plugins/' . $plugin_name . '/'
355 . $this->get_template_file_directory()
356 . substr($filename, strlen($plugin_name) +
9);
358 // no go, we have to get the default template,
359 // first try the default SM template
361 if (!file_exists($filepath)) {
364 . $this->get_default_template_file_directory()
367 // still no luck? get default template from the plugin
369 if (!file_exists($filepath)) {
371 $filepath = SM_PATH
. 'plugins/' . $plugin_name . '/'
372 . $this->get_default_template_file_directory()
373 . substr($filename, strlen($plugin_name) +
9);
375 // we're almost out of luck, try hard-coded default...
377 if (!file_exists($filepath)) {
379 $filepath = SM_PATH
. 'plugins/' . $plugin_name
380 . '/templates/default/'
381 . substr($filename, strlen($plugin_name) +
9);
383 // no dice whatsoever, return empty string
385 if (!file_exists($filepath)) {
396 // get default template for non-plugin templates
400 $filepath = SM_PATH
. $this->get_default_template_file_directory()
403 // no dice whatsoever, return empty string
405 if (!file_exists($filepath)) {
418 * Return the list of javascript files required by this
419 * template set. Only files that actually exist are returned.
421 * @param boolean $full_path When FALSE, only the file names
422 * are included in the return array;
423 * otherwise, path information is
424 * included (relative to SM_PATH)
425 * (OPTIONAL; default only file names)
427 * @return array The required file names/paths.
430 function get_javascript_includes($full_path=FALSE) {
432 //FIXME -- change this system so it just returns whatever is in js dir?
433 // bah, maybe not, but we might want to enhance this to pull in
434 // js files not found in this or the default template from SM_PATH/js???
436 foreach ($this->required_js_files
as $file) {
437 $file = $this->get_template_file_path('js/' . $file);
442 $paths[] = basename($file);
452 * Return all standard stylsheets provided by the template.
454 * All files found in the template set's "css" directory with
455 * the extension ".css" except "rtl.css" (which is dealt with
456 * separately) are returned.
458 * @param boolean $full_path When FALSE, only the file names
459 * are included in the return array;
460 * otherwise, path information is
461 * included (relative to SM_PATH)
462 * (OPTIONAL; default only file names)
464 * @return array The required file names/paths.
467 function get_stylesheets($full_path=FALSE) {
469 $directory = SM_PATH
. $this->get_template_file_directory() . 'css';
470 $files = list_files($directory, '.css', !$full_path);
472 // need to leave out "rtl.css"
474 $return_array = array();
475 foreach ($files as $file) {
477 if (strtolower(basename($file)) == 'rtl.css') {
481 $return_array[] = $file;
485 return $return_array;
490 * Generate links to all this template set's standard stylesheets
492 * Subclasses can override this function if stylesheets are
493 * created differently for the template set's target output
496 * @return string The stylesheet links as they should be sent
500 function fetch_standard_stylesheet_links()
503 $sheets = $this->get_stylesheets(TRUE);
504 return $this->fetch_external_stylesheet_links($sheets);
509 * Push out any other stylesheet links as provided (for
510 * stylesheets not included with the current template set)
512 * Subclasses can override this function if stylesheets are
513 * created differently for the template set's target output
516 * @param mixed $sheets List of the desired stylesheets
517 * (file path to be used in stylesheet
518 * href attribute) to output (or single
519 * stylesheet file path).
520 FIXME: We could make the incoming array more complex so it can
521 also contain the other parameters for create_css_link()
522 such as $name, $alt, $mtype, and $xhtml_end
525 * @return string The stylesheet links as they should be sent
529 function fetch_external_stylesheet_links($sheets)
532 if (!is_array($sheets)) $sheets = array($sheets);
535 foreach ($sheets as $sheet) {
536 $output .= create_css_link($sheet);
544 * Send HTTP header(s) to browser.
546 * Subclasses can override this function if headers are
547 * managed differently in the template set's target output
550 * @param mixed $headers A list of (or a single) header
554 function header($headers)
557 if (!is_array($headers)) $headers = array($headers);
559 foreach ($headers as $header) {
566 * Generate a link to the right-to-left stylesheet for
567 * this template set, or use the one for the default
568 * template set if not found, or finally, fall back
569 * to SquirrelMail's own "rtl.css" if need be.
571 * Subclasses can override this function if stylesheets are
572 * created differently for the template set's target output
575 * @return string The stylesheet link as it should be sent
579 function fetch_right_to_left_stylesheet_link()
582 // get right template file
584 $sheet = $this->get_template_file_path('css/rtl.css');
586 // fall back to SquirrelMail's own default stylesheet
589 $sheet = SM_PATH
. 'css/rtl.css';
592 return create_css_link($sheet);
597 * Display the template
599 * @param string $file The template file to use
602 function display($file)
605 echo $this->fetch($file);
610 * Applies the template and returns the resultant content string.
612 * @param string $file The template file to use
614 * @return string The template contents after applying the given template
617 function fetch($file) {
619 // get right template file
621 $template = $this->get_template_file_path($file);
623 // special case stylesheet.tpl falls back to SquirrelMail's
624 // own default stylesheet
626 if (empty($template) && $file == 'css/stylesheet.tpl') {
627 $template = SM_PATH
. 'css/default.css';
630 if (empty($template)) {
632 trigger_error('The template "' . htmlspecialchars($file)
633 . '" could not be fetched!', E_USER_ERROR
);
637 $aPluginOutput = array();
638 $aPluginOutput = concat_hook_function('template_construct_' . $file,
639 array($aPluginOutput, $this));
640 $this->assign('plugin_output', $aPluginOutput);
642 $output = $this->apply_template($template);
644 // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
645 // RESULT IN NOTICABLE PERFORMANCE DEGREDATION. Plugins
646 // using this hook will probably be rejected by the
647 // SquirrelMail team.
649 $output = filter_hook_function('template_output', $output);
658 * Assigns values to template variables
660 * Note: this is an abstract method that must be implemented by subclass.
662 * @param array|string $tpl_var the template variable name(s)
663 * @param mixed $value the value to assign
666 function assign($tpl_var, $value = NULL) {
668 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the assign() method.', E_USER_ERROR
);
673 * Assigns values to template variables by reference
675 * Note: this is an abstract method that must be implemented by subclass.
677 * @param string $tpl_var the template variable name
678 * @param mixed $value the referenced value to assign
681 function assign_by_ref($tpl_var, &$value) {
683 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the assign_by_ref() method.', E_USER_ERROR
);
688 * Appends values to template variables
690 * Note: this is an abstract method that must be implemented by subclass.
692 * @param array|string $tpl_var the template variable name(s)
693 * @param mixed $value the value to append
694 * @param boolean $merge when $value is given as an array,
695 * this indicates whether or not that
696 * array itself should be appended as
697 * a new template variable value or if
698 * that array's values should be merged
699 * into the existing array of template
703 function append($tpl_var, $value = NULL, $merge = FALSE) {
705 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the append() method.', E_USER_ERROR
);
710 * Appends values to template variables by reference
712 * Note: this is an abstract method that must be implemented by subclass.
714 * @param string $tpl_var the template variable name
715 * @param mixed $value the referenced value to append
716 * @param boolean $merge when $value is given as an array,
717 * this indicates whether or not that
718 * array itself should be appended as
719 * a new template variable value or if
720 * that array's values should be merged
721 * into the existing array of template
725 function append_by_ref($tpl_var, &$value, $merge = FALSE) {
727 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the append_by_ref() method.', E_USER_ERROR
);
732 * Applys the template and generates final output destined
733 * for the user's browser
735 * Note: this is an abstract method that must be implemented by subclass.
737 * @param string $filepath The full file path to the template to be applied
739 * @return string The output for the given template
742 function apply_template($filepath) {
744 trigger_error('Template subclass (' . $this->template_engine
. 'Template.class.php) needs to implement the apply_template() method.', E_USER_ERROR
);