class/template/Template.class.php

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