The fall-back template engine (please use constants defined in constants.php)

Extra template engine class objects for rendering templates that require a different engine than the one for the current template set. Keys should be the name of the template engine, values are the corresponding class objects.

The template engine (please use constants defined in constants.php)

The template ID

Determine the relative template directory path for the given template ID.

• return: The relative template path (based off of SM_PATH)

• string $template_set_id: The template ID from which to build the directory path

Traverse template hierarchy and catalogue all template files (for storing in cache).

Paths to all files in all parent, grand-parent, great grand parent, etc. template sets (including the fallback template) are catalogued; for identically named files, the file earlier in the hierarchy (closest to this template set) is used.

• return: The top-level caller will have an array of template files returned to it; recursive calls to this function do not receive any return value at all. The format of the template file array is as described for the Template class attribute $template_file_cache

• string $template_set_id: The template set in which to search for files
• array $file_list: The file list so far to be added to (allows recursive behavior) (optional; default empty array).
• string $directory: The directory in which to search for files (must be given as full path). If empty, starts at top-level template set directory (optional; default empty). NOTE! Use with care, as behavior is unpredictable if directory given is not part of correct template set.

Determine what the default template set is.

NOTE that if the default setting cannot be found in the main SquirrelMail configuration settings that the value of $default is returned.

• return: The ID of the default template set.

• string $default: The template set ID to use if the default setting cannot be found in SM config (optional; defaults to "default").

Get template set config setting

Given a template set ID and setting name, returns the setting's value. Note that settings are cached in session, so "live" changes to template configuration won't be reflected until the user logs out and back in again.

• return: The desired setting's value or if not found, the contents of $default are returned.

• string $template_set_id: The template set for which to look up the setting.
• string $setting: The name of the setting to retrieve.
• mixed $default: When the requested setting is not found, the contents of this value are returned instead (optional; default is NULL). NOTE that unlike sqGetGlobalVar(), this function will also return the default value if the requested setting is found but is empty.
• boolean $live_config: When TRUE, the target template set's configuration file is reloaded every time this method is called. Default behavior is to only load the configuration file if it had never been loaded before, but not again after that (optional; default FALSE). Use with care! Should mostly be used for debugging.

Appends values to template variables

Note: this is an abstract method that must be implemented by subclass.

• array|string $tpl_var: the template variable name(s)
• mixed $value: the value to append
• boolean $merge: when $value is given as an array, this indicates whether or not that array itself should be appended as a new template variable value or if that array's values should be merged into the existing array of template variable values

• PHP_Template::append() : Appends values to template variables
• Smarty_Template::append() : Appends values to template variables

Applys the template and generates final output destined for the user's browser

Note: this is an abstract method that must be implemented by subclass.

• return: The output for the given template

• string $filepath: The full file path to the template to be applied

• PHP_Template::apply_template() : Applys the template and generates final output destined for the user's browser
• Smarty_Template::apply_template() : Applys the template and generates final output destined for the user's browser

Assigns values to template variables by reference

Note: this is an abstract method that must be implemented by subclass.

• string $tpl_var: the template variable name
• mixed $value: the referenced value to assign
• &$value

• PHP_Template::assign_by_ref() : Assigns values to template variables by reference
• Smarty_Template::assign_by_ref() : Assigns values to template variables by reference

Display the template

• string $file: The template file to use

Push out any other stylesheet links as provided (for stylesheets not included with the current template set)

Subclasses can override this function if stylesheets are created differently for the template set's target output interface.

• return: The stylesheet links as they should be sent to the browser.

• mixed $sheets: List of the desired stylesheets (file path to be used in stylesheet href attribute) to output (or single stylesheet file path).

Generate links to all this template set's standard stylesheets

Subclasses can override this function if stylesheets are created differently for the template set's target output interface.

• return: The stylesheet links as they should be sent to the browser.

Return all alternate stylesheets provided by template.

All files found in the template set's "css/alternates" directory (and that of its ancestors) with the extension ".css" are returned.

Note that prettified names are constructed herein by taking the file name, changing underscores to spaces, removing the ".css" from the end of the file, and capitalizing each word in the resultant name.

• return: A list of the available alternate stylesheets, where the keys are the file names (formatted according to $full_path) for the stylesheets, and the values are the prettified version of the file names for display to the user.

• boolean $full_path: When FALSE, only the file names are included in the return array; otherwise, path information is included (relative to SM_PATH) (OPTIONAL; default only file names)

Return the template ID for the fallback template set.

• return: The ID of the fallback template set.

Get template engine needed to render given template file.

If at all possible, just returns a reference to $this, but some template files may require a different engine, thus an object for that engine (which will subsequently be kept in this object for future use) is returned.

• return: needed template object to render the template.

• string $filename: The name of the template file,

Instantiate and return correct subclass for this template set's templating engine.

• return: Template subclass object for the template engine.

• string $template_set_id: The template set whose engine is to be used as an override (if not given, this template set's engine is used) (optional).

Find the right template file.

The template file is taken from the template file cache, thus the file is taken from the current template, one of its ancestors or the fallback template.

Note that it is perfectly acceptable to load template files from template subdirectories. For example, JavaScript templates found in the js/ subdirectory would be loaded by passing "js/<javascript file name>" as the $filename.

Note that the caller can also ask for ALL files in a directory (and those in the same directory for all ancestor template sets) by giving a $filename that is a directory name (ending with a slash).

If not found and the file is a plugin template file (indicated by the presence of "plugins/" on the beginning of $filename), the target plugin is searched for a substitue template file before just returning nothing.

Plugin authors must note that the $filename MUST be prefaced with "plugins/<plugin name>/" in order to correctly resolve the template file.

• return: The full path to the template file or a list of all files in the given directory if $filename ends with a slash; if not found, an empty string is returned. The caller is responsible for throwing errors or other actions if template file is not found.

• string $filename: The name of the template file, possibly prefaced with "plugins/<plugin name>/" indicating that it is a plugin template, or ending with a slash, indicating that all files for that directory name should be returned.

Send HTTP header(s) to browser.

Subclasses can override this function if headers are managed differently in the template set's target output interface.

• mixed $headers: A list of (or a single) header text to be sent.