The fall-back template directory (relative path from the main SquirrelMail directory (SM_PATH))

The fall-back template ID

The template set base directory (relative path from the main SquirrelMail directory (SM_PATH))

Template file cache. Structured as an array, whose keys

are all the template file names (with path information relative to the template set's base directory, e.g., "css/style.css") found in all parent template sets including the ultimate fall-back template set. Array values are sub-arrays with the following key-value pairs:

PATH -- file path, relative to SM_PATH SET_ID -- the ID of the template set that this file belongs to ENGINE -- the engine needed to render this template file

Obtain template file hierarchy from cache.

If the file hierarchy does not exist in session, it is constructed and stored in session before being returned to the caller.

• return:

  Template file hierarchy array, whose keys are all the template file names for the given template set ID (with path information relative to the template set's base directory, e.g., "css/style.css") found in all parent template sets including the ultimate fall-back template set. Array values are sub-arrays with the following key-value pairs:

  PATH -- file path, relative to SM_PATH SET_ID -- the ID of the template set that this file belongs to ENGINE -- the engine needed to render this template file

• string $template_set_id: The template set for which the cache should be built. This function will save more than one set's files, so it may be called multiple times with different values for this argument. When regenerating, all set caches are dumped.
• boolean $regenerate_cache: When TRUE, the file hierarchy is reloaded and stored fresh (optional; default FALSE).
• array $additional_files: Must be in same form as the files in the file hierarchy cache. These are then added to the cache (optional; default empty - no additional files).

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

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

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

Construct Template

This method should always be called instead of trying to get a Template object from the normal/default constructor, and is necessary in order to control the return value.

• return: correct Template object for the given template set

• string $template_set_id: the template ID

Determine what the ultimate fallback template set is.

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

• return: The ID of the fallback template set.

• string $default: The template set ID to use if the fallback 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

• Smarty_Template::append() : Appends values to template variables
• PHP_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

• Smarty_Template::apply_template() : Applys the template and generates final output destined for the user's browser
• PHP_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

• Smarty_Template::assign_by_ref() : Assigns values to template variables by reference
• PHP_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 (non-empty) directories found in the template set's "css/alternates" directory (and that of its ancestors) are returned.

Note that prettified names are constructed herein by taking the directory name, changing underscores to spaces 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 relative template directory path for the fallback template set.

• return: The relative path to the fallback template directory based from the main SquirrelMail directory (SM_PATH).

Return all JavaScript files provided by the template.

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

• return: The required file names/paths.

• 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 all standard stylsheets provided by the template.

All files found in the template set's "css" directory (and that of its ancestors) with the extension ".css" except "rtl.css" (which is dealt with separately) are returned.

• return: The required file names/paths.

• 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 relative template directory path for this template set.

• return: The relative path to the template directory based from the main SquirrelMail directory (SM_PATH).

Returns assigned variable value(s).

• return: Desired single variable value or list of all assigned variable values.

• string $varname: If given, the value of that variable is returned, assuming it has been previously assigned. If not specified an array of all assigned variables is returned. (optional)

• Smarty_Template::get_template_vars() : Returns assigned variable value(s).
• PHP_Template::get_template_vars() : Returns assigned variable value(s).

Allow template set to override plugin configuration by either adding or removing plugins.

NOTE: due to when this code executes, plugins activated here do not have access to the config_override and loading_prefs hooks; instead, such plugins can use the "template_plugins_override_after" hook defined below.