Source for file Template.class.php

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

Documentation generated on Sat, 07 Oct 2006 16:13:56 +0300 by phpDocumentor 1.3.0RC6