class/template/Template.class.php

   1 <?php
   2
   3 require(SM_PATH . 'functions/template.php');
   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()
  34   *     append()
  35   *     append_by_ref()
  36   *     apply_template()
  37   *
  38   * @author Paul Lesniewski
  39   * @package squirrelmail
  40   *
  41   */
  42 class Template
  43 {
  44
  45     /**
  46       * The template ID
  47       *
  48       * @var string
  49       *
  50       */
  51     var $template_id = '';
  52
  53     /**
  54       * The template directory to use
  55       *
  56       * @var string
  57       *
  58       */
  59     var $template_dir = '';
  60
  61     /**
  62       * The template engine (please use constants defined in constants.php)
  63       *
  64       * @var string
  65       *
  66       */
  67     var $template_engine = '';
  68
  69     /**
  70       * The default template ID
  71       *
  72       * @var string
  73       *
  74       */
  75     var $default_template_id = '';
  76
  77     /**
  78       * The default template directory
  79       *
  80       * @var string
  81       *
  82       */
  83     var $default_template_dir = '';
  84
  85     /**
  86       * The default template engine (please use constants defined in constants.php)
  87       *
  88       * @var string
  89       *
  90       */
  91     var $default_template_engine = '';
  92
  93     /**
  94       * Javascript files required by the template
  95       *
  96       * @var array
  97       *
  98       */
  99     var $required_js_files = array();
 100
 101     /**
 102      * Alternate stylesheets provided by the template.  This is defined in the
 103      * template config file so that we can provide pretty names in the display
 104      * preferences
 105      *
 106      * @var array
 107      **/
 108     var $alternate_stylesehets = array();
 109
 110     /**
 111       * Constructor
 112       *
 113       * Please do not call directly.  Use Template::construct_template().
 114       *
 115       * @param string $template_id the template ID
 116       *
 117       */
 118     function Template($template_id) {
 119 //FIXME: find a way to test that this is ONLY ever called
 120 //       from the construct_template() method (I doubt it
 121 //       is worth the trouble to parse the current stack trace)
 122 //        if (???)
 123 //            trigger_error('Please do not use default Template() constructor.  Instead, use Template::construct_template().', E_USER_ERROR);
 124
 125         $this->set_up_template($template_id);
 126
 127     }
 128
 129     /**
 130       * Construct Template
 131       *
 132       * This method should always be called instead of trying
 133       * to get a Template object from the normal/default constructor,
 134       * and is necessary in order to control the return value.
 135       *
 136       * @param string $template_id the template ID
 137       *
 138       * @return object The correct Template object for the given template set
 139       *
 140       */
 141     function construct_template($template_id) {
 142
 143         $template = new Template($template_id);
 144         return $template->get_template_engine_subclass();
 145
 146     }
 147
 148     /**
 149       * Set up internal attributes
 150       *
 151       * This method does most of the work for setting up
 152       * newly constructed objects.
 153       *
 154       * @param string $template_id the template ID
 155       *
 156       */
 157     function set_up_template($template_id) {
 158
 159         // FIXME: do we want to place any restrictions on the ID like
 160         //        making sure no slashes included?
 161         // get template ID
 162         //
 163         $this->template_id = $template_id;
 164
 165
 166         // FIXME: do we want to place any restrictions on the ID like
 167         //        making sure no slashes included?
 168         // get default template ID
 169         //
 170         global $templateset_default, $aTemplateSet;
 171         $aTemplateSet = (!isset($aTemplateSet) || !is_array($aTemplateSet)
 172                          ? array() : $aTemplateSet);
 173         $templateset_default = (!isset($templateset_default) ? 0 : $templateset_default);
 174         $this->default_template_id = (!empty($aTemplateSet[$templateset_default]['ID'])
 175                                       ? $aTemplateSet[$templateset_default]['ID']
 176                                       : 'default');
 177
 178
 179         // set up template directories
 180         //
 181         $this->template_dir
 182             = Template::calculate_template_file_directory($this->template_id);
 183         $this->default_template_dir
 184             = Template::calculate_template_file_directory($this->default_template_id);
 185
 186
 187         // pull in the template config file and load javascript and
 188         // css files needed for this template set
 189         //
 190         $template_config_file = SM_PATH . $this->get_template_file_directory()
 191                               . 'config.php';
 192         if (!file_exists($template_config_file)) {
 193
 194             trigger_error('No template configuration file was found where expected: ("'
 195                         . $template_config_file . '")', E_USER_ERROR);
 196
 197         } else {
 198
 199             require($template_config_file);
 200             $this->required_js_files = is_array($required_js_files)
 201                                      ? $required_js_files : array();
 202             $this->alternate_stylesheets = is_array($alternate_stylesheets) ?
 203                                            $alternate_stylesheets :
 204                                            array();
 205
 206         }
 207
 208
 209         // determine template engine
 210         //
 211         if (empty($template_engine)) {
 212             trigger_error('No template engine ($template_engine) was specified in template configuration file: ("'
 213                         . $template_config_file . '")', E_USER_ERROR);
 214         } else {
 215             $this->template_engine = $template_engine;
 216         }
 217
 218     }
 219
 220     /**
 221       * Instantiate and return correct subclass for this template
 222       * set's templating engine.
 223       *
 224       * @return object The Template subclass object for the template engine.
 225       *
 226       */
 227     function get_template_engine_subclass() {
 228
 229         $engine_class_file = SM_PATH . 'class/template/'
 230                            . $this->template_engine . 'Template.class.php';
 231
 232         if (!file_exists($engine_class_file)) {
 233             trigger_error('Unknown template engine (' . $this->template_engine
 234                         . ') was specified in template configuration file',
 235                          E_USER_ERROR);
 236         }
 237
 238         $engine_class = $this->template_engine . 'Template';
 239         require($engine_class_file);
 240         return new $engine_class($this->template_id);
 241
 242     }
 243
 244     /**
 245       * Determine the relative template directory path for
 246       * the given template ID.
 247       *
 248       * @param string $template_id The template ID from which to build
 249       *                            the directory path
 250       *
 251       * @return string The relative template path (based off of SM_PATH)
 252       *
 253       */
 254     function calculate_template_file_directory($template_id) {
 255
 256         return 'templates/' . $template_id . '/';
 257
 258     }
 259
 260     /**
 261       * Determine the relative images directory path for
 262       * the given template ID.
 263       *
 264       * @param string $template_id The template ID from which to build
 265       *                            the directory path
 266       *
 267       * @return string The relative images path (based off of SM_PATH)
 268       *
 269       */
 270     function calculate_template_images_directory($template_id) {
 271
 272         return 'templates/' . $template_id . '/images/';
 273
 274     }
 275
 276     /**
 277       * Return the relative template directory path for this template set.
 278       *
 279       * @return string The relative path to the template directory based
 280       *                from the main SquirrelMail directory (SM_PATH).
 281       *
 282       */
 283     function get_template_file_directory() {
 284
 285         return $this->template_dir;
 286
 287     }
 288
 289
 290     /**
 291       * Return the relative template directory path for the DEFAULT template set.
 292       *
 293       * @return string The relative path to the default template directory based
 294       *                from the main SquirrelMail directory (SM_PATH).
 295       *
 296       */
 297     function get_default_template_file_directory() {
 298
 299         return $this->default_template_dir;
 300
 301     }
 302
 303
 304     /**
 305       * Find the right template file.
 306       *
 307       * Templates are expected to be found in the template set directory,
 308       * for example:
 309       *     SM_PATH/templates/<template name>/
 310       * or, in the case of plugin templates, in a plugin directory in the
 311       * template set directory, for example:
 312       *     SM_PATH/templates/<template name>/plugins/<plugin name>/
 313       * *OR* in a template directory in the plugin as a fallback, for example:
 314       *     SM_PATH/plugins/<plugin name>/templates/<template name>/
 315       * If the correct file is not found for the current template set, a
 316       * default template is loaded, which is expected to be found in the
 317       * default template directory, for example:
 318       *     SM_PATH/templates/<default template>/
 319       * or for plugins, in a plugin directory in the default template set,
 320       * for example:
 321       *     SM_PATH/templates/<default template>/plugins/<plugin name>/
 322       * *OR* in a default template directory in the plugin as a fallback,
 323       * for example:
 324       *     SM_PATH/plugins/<plugin name>/templates/<default template>/
 325       * *OR* if the plugin template still cannot be found, one last attempt
 326       * will be made to load it from a hard-coded default template directory
 327       * inside the plugin:
 328       *     SM_PATH/plugins/<plugin name>/templates/default/
 329       *
 330       * Plugin authors must note that the $filename MUST be prefaced
 331       * with "plugins/<plugin name>/" in order to correctly resolve the
 332       * template file.
 333       *
 334       * Note that it is perfectly acceptable to load template files from
 335       * template subdirectories other than plugins; for example, JavaScript
 336       * templates found in the js/ subdirectory would be loaded by passing
 337       * "js/<javascript file name>" as the $filename.
 338       *
 339       * @param string $filename The name of the template file,
 340       *                         possibly prefaced with
 341       *                         "plugins/<plugin name>/"
 342       *                         indicating that it is a plugin
 343       *                         template.
 344       *
 345       * @return string The full path to the template file; if
 346       *                not found, an empty string.  The caller
 347       *                is responsible for throwing erros or
 348       *                other actions if template file is not found.
 349       *
 350       */
 351     function get_template_file_path($filename) {
 352
 353         // is the template found in the normal template directory?
 354         //
 355         $filepath = SM_PATH . $this->get_template_file_directory() . $filename;
 356         if (!file_exists($filepath)) {
 357
 358             // no, so now we have to get the default template...
 359             // however, in the case of a plugin template, let's
 360             // give one more try to find the right template as
 361             // provided by the plugin
 362             //
 363             if (strpos($filename, 'plugins/') === 0) {
 364
 365                 $plugin_name = substr($filename, 8, strpos($filename, '/', 8) - 8);
 366                 $filepath = SM_PATH . 'plugins/' . $plugin_name . '/'
 367                           . $this->get_template_file_directory()
 368                           . substr($filename, strlen($plugin_name) + 9);
 369
 370                 // no go, we have to get the default template,
 371                 // first try the default SM template
 372                 //
 373                 if (!file_exists($filepath)) {
 374
 375                     $filepath = SM_PATH
 376                               . $this->get_default_template_file_directory()
 377                               . $filename;
 378
 379                     // still no luck?  get default template from the plugin
 380                     //
 381                     if (!file_exists($filepath)) {
 382
 383                         $filepath = SM_PATH . 'plugins/' . $plugin_name . '/'
 384                                   . $this->get_default_template_file_directory()
 385                                   . substr($filename, strlen($plugin_name) + 9);
 386
 387                         // we're almost out of luck, try hard-coded default...
 388                         //
 389                         if (!file_exists($filepath)) {
 390
 391                             $filepath = SM_PATH . 'plugins/' . $plugin_name
 392                                       . '/templates/default/'
 393                                       . substr($filename, strlen($plugin_name) + 9);
 394
 395                             // no dice whatsoever, return empty string
 396                             //
 397                             if (!file_exists($filepath)) {
 398                                 $filepath = '';
 399                             }
 400
 401                         }
 402
 403                     }
 404
 405                 }
 406
 407
 408             // get default template for non-plugin templates
 409             //
 410             } else {
 411
 412                 $filepath = SM_PATH . $this->get_default_template_file_directory()
 413                           . $filename;
 414
 415                 // no dice whatsoever, return empty string
 416                 //
 417                 if (!file_exists($filepath)) {
 418                     $filepath = '';
 419                 }
 420
 421             }
 422
 423         }
 424
 425         return $filepath;
 426
 427     }
 428
 429     /**
 430       * Return the list of javascript files required by this
 431       * template set.  Only files that actually exist are returned.
 432       *
 433       * @param boolean $full_path When FALSE, only the file names
 434       *                           are included in the return array;
 435       *                           otherwise, path information is
 436       *                           included (relative to SM_PATH)
 437       *                           (OPTIONAL; default only file names)
 438       *
 439       * @return array The required file names/paths.
 440       *
 441       */
 442     function get_javascript_includes($full_path=FALSE) {
 443
 444 //FIXME -- change this system so it just returns whatever is in js dir?
 445 //         bah, maybe not, but we might want to enhance this to pull in
 446 //         js files not found in this or the default template from SM_PATH/js???
 447         $paths = array();
 448         foreach ($this->required_js_files as $file) {
 449             $file = $this->get_template_file_path('js/' . $file);
 450             if (!empty($file)) {
 451                 if ($full_path) {
 452                     $paths[] = $file;
 453                 } else {
 454                     $paths[] = basename($file);
 455                 }
 456             }
 457         }
 458
 459         return $paths;
 460
 461     }
 462
 463     /**
 464       * Return all standard stylsheets provided by the template.
 465       *
 466       * All files found in the template set's "css" directory with
 467       * the extension ".css" except "rtl.css" (which is dealt with
 468       * separately) are returned.
 469       *
 470       * @param boolean $full_path When FALSE, only the file names
 471       *                           are included in the return array;
 472       *                           otherwise, path information is
 473       *                           included (relative to SM_PATH)
 474       *                           (OPTIONAL; default only file names)
 475       *
 476       * @return array The required file names/paths.
 477       *
 478       */
 479     function get_stylesheets($full_path=FALSE) {
 480
 481         $directory = SM_PATH . $this->get_template_file_directory() . 'css';
 482         $files = list_files($directory, '.css', !$full_path);
 483
 484         // need to leave out "rtl.css"
 485         $return_array = array();
 486         foreach ($files as $file) {
 487
 488             if (strtolower(basename($file)) == 'rtl.css') {
 489                 continue;
 490             }
 491
 492             $return_array[] = $file;
 493
 494         }
 495
 496         return $return_array;
 497
 498     }
 499
 500     /**
 501      * Return all alternate stylesheets provided by template.  These
 502      * sheets are defined in the template config file so that we cna display
 503      * pretty names in the Display Preferences.  The CSS files are located in
 504      * $this->template_dir/css/alternatives/
 505      *
 506      * @return array alternate style sheets
 507      **/
 508     function get_alternative_stylesheets () {
 509         $a = array();
 510         foreach ($this->alternate_stylesheets as $path=>$name) {
 511             $a[strtolower(basename($path))] = $name;
 512         }
 513         return $a;
 514     }
 515
 516     /**
 517       * Generate links to all this template set's standard stylesheets
 518       *
 519       * Subclasses can override this function if stylesheets are
 520       * created differently for the template set's target output
 521       * interface.
 522       *
 523       * @return string The stylesheet links as they should be sent
 524       *                to the browser.
 525       *
 526       */
 527     function fetch_standard_stylesheet_links()
 528     {
 529
 530         $sheets = $this->get_stylesheets(TRUE);
 531         return $this->fetch_external_stylesheet_links($sheets);
 532
 533     }
 534
 535     /**
 536       * Push out any other stylesheet links as provided (for
 537       * stylesheets not included with the current template set)
 538       *
 539       * Subclasses can override this function if stylesheets are
 540       * created differently for the template set's target output
 541       * interface.
 542       *
 543       * @param mixed $sheets List of the desired stylesheets
 544       *                      (file path to be used in stylesheet
 545       *                      href attribute) to output (or single
 546       *                      stylesheet file path).
 547 FIXME: We could make the incoming array more complex so it can
 548        also contain the other parameters for create_css_link()
 549        such as $name, $alt, $mtype, and $xhtml_end
 550        But do we need to?
 551       *
 552       * @return string The stylesheet links as they should be sent
 553       *                to the browser.
 554       *
 555       */
 556     function fetch_external_stylesheet_links($sheets)
 557     {
 558
 559         if (!is_array($sheets)) $sheets = array($sheets);
 560         $output = '';
 561
 562         foreach ($sheets as $sheet) {
 563             $output .= create_css_link($sheet);
 564         }
 565
 566         return $output;
 567
 568     }
 569
 570     /**
 571       * Send HTTP header(s) to browser.
 572       *
 573       * Subclasses can override this function if headers are
 574       * managed differently in the template set's target output
 575       * interface.
 576       *
 577       * @param mixed $headers A list of (or a single) header
 578       *                       text to be sent.
 579       *
 580       */
 581     function header($headers)
 582     {
 583
 584         if (!is_array($headers)) $headers = array($headers);
 585
 586         foreach ($headers as $header) {
 587             header($header);
 588         }
 589
 590     }
 591
 592     /**
 593       * Generate a link to the right-to-left stylesheet for
 594       * this template set, or use the one for the default
 595       * template set if not found, or finally, fall back
 596       * to SquirrelMail's own "rtl.css" if need be.
 597       *
 598       * Subclasses can override this function if stylesheets are
 599       * created differently for the template set's target output
 600       * interface.
 601       *
 602       * @return string The stylesheet link as it should be sent
 603       *                to the browser.
 604       *
 605       */
 606     function fetch_right_to_left_stylesheet_link()
 607     {
 608
 609         // get right template file
 610         //
 611         $sheet = $this->get_template_file_path('css/rtl.css');
 612
 613         // fall back to SquirrelMail's own default stylesheet
 614         //
 615         if (empty($sheet)) {
 616             $sheet = SM_PATH . 'css/rtl.css';
 617         }
 618
 619         return create_css_link($sheet);
 620
 621     }
 622
 623     /**
 624       * Display the template
 625       *
 626       * @param string $file The template file to use
 627       *
 628       */
 629     function display($file)
 630     {
 631
 632         echo $this->fetch($file);
 633
 634     }
 635
 636     /**
 637       * Applies the template and returns the resultant content string.
 638       *
 639       * @param string $file The template file to use
 640       *
 641       * @return string The template contents after applying the given template
 642       *
 643       */
 644     function fetch($file) {
 645
 646         // get right template file
 647         //
 648         $template = $this->get_template_file_path($file);
 649
 650         // special case stylesheet.tpl falls back to SquirrelMail's
 651         // own default stylesheet
 652         //
 653         if (empty($template) && $file == 'css/stylesheet.tpl') {
 654             $template = SM_PATH . 'css/default.css';
 655         }
 656
 657         if (empty($template)) {
 658
 659             trigger_error('The template "' . htmlspecialchars($file)
 660                           . '" could not be fetched!', E_USER_ERROR);
 661
 662         } else {
 663
 664             $aPluginOutput = array();
 665             $aPluginOutput = concat_hook_function('template_construct_' . $file,
 666                                                   array($aPluginOutput, $this));
 667             $this->assign('plugin_output', $aPluginOutput);
 668
 669             $output = $this->apply_template($template);
 670
 671             // CAUTION: USE OF THIS HOOK IS HIGHLY DISCOURAGED AND CAN
 672             // RESULT IN NOTICABLE PERFORMANCE DEGREDATION.  Plugins
 673             // using this hook will probably be rejected by the
 674             // SquirrelMail team.
 675             //
 676             $output = filter_hook_function('template_output', $output);
 677
 678             return $output;
 679
 680         }
 681
 682     }
 683
 684     /**
 685       * Assigns values to template variables
 686       *
 687       * Note: this is an abstract method that must be implemented by subclass.
 688       *
 689       * @param array|string $tpl_var the template variable name(s)
 690       * @param mixed $value the value to assign
 691       *
 692       */
 693     function assign($tpl_var, $value = NULL) {
 694
 695         trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the assign() method.', E_USER_ERROR);
 696
 697     }
 698
 699     /**
 700       * Assigns values to template variables by reference
 701       *
 702       * Note: this is an abstract method that must be implemented by subclass.
 703       *
 704       * @param string $tpl_var the template variable name
 705       * @param mixed $value the referenced value to assign
 706       *
 707       */
 708     function assign_by_ref($tpl_var, &$value) {
 709
 710         trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the assign_by_ref() method.', E_USER_ERROR);
 711
 712     }
 713
 714     /**
 715       * Appends values to template variables
 716       *
 717       * Note: this is an abstract method that must be implemented by subclass.
 718       *
 719       * @param array|string $tpl_var the template variable name(s)
 720       * @param mixed $value the value to append
 721       * @param boolean $merge when $value is given as an array,
 722       *                       this indicates whether or not that
 723       *                       array itself should be appended as
 724       *                       a new template variable value or if
 725       *                       that array's values should be merged
 726       *                       into the existing array of template
 727       *                       variable values
 728       *
 729       */
 730     function append($tpl_var, $value = NULL, $merge = FALSE) {
 731
 732         trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the append() method.', E_USER_ERROR);
 733
 734     }
 735
 736     /**
 737       * Appends values to template variables by reference
 738       *
 739       * Note: this is an abstract method that must be implemented by subclass.
 740       *
 741       * @param string $tpl_var the template variable name
 742       * @param mixed $value the referenced value to append
 743       * @param boolean $merge when $value is given as an array,
 744       *                       this indicates whether or not that
 745       *                       array itself should be appended as
 746       *                       a new template variable value or if
 747       *                       that array's values should be merged
 748       *                       into the existing array of template
 749       *                       variable values
 750       *
 751       */
 752     function append_by_ref($tpl_var, &$value, $merge = FALSE) {
 753
 754         trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the append_by_ref() method.', E_USER_ERROR);
 755
 756     }
 757
 758     /**
 759       * Applys the template and generates final output destined
 760       * for the user's browser
 761       *
 762       * Note: this is an abstract method that must be implemented by subclass.
 763       *
 764       * @param string $filepath The full file path to the template to be applied
 765       *
 766       * @return string The output for the given template
 767       *
 768       */
 769     function apply_template($filepath) {
 770
 771         trigger_error('Template subclass (' . $this->template_engine . 'Template.class.php) needs to implement the apply_template() method.', E_USER_ERROR);
 772
 773     }
 774
 775 }
 776