Class Template

Description

The SquirrelMail Template class.

Basic template class for capturing values and pluging them into a template. This class uses a similar API to Smarty.

Methods that must be implemented by subclasses are as follows (see method stubs below for further information about expected behavior):

assign() assign_by_ref() clear_all_assign() get_template_vars() append() append_by_ref() apply_template()

  • author: Paul Lesniewski

Located in /class/template/Template.class.php (line 44)


	
			
Direct descendents
Class Description
PHP_Template The SquirrelMail PHP Template class. Extends the base Template class for use with PHP template pages.
Smarty_Template The SquirrelMail Smarty Template class. Extends the base Template class for use with Smarty template pages.
Variable Summary
Method Summary
static array cache_template_file_hierarchy ([boolean $regenerate_cache = FALSE], [array $additional_files = array()])
static string calculate_template_file_directory (string $template_set_id)
static string calculate_template_images_directory (string $template_set_id)
static mixed catalog_template_files (string $template_set_id, [array $file_list = array()], [string $directory = ''])
static object The construct_template (string $template_set_id)
static string get_default_template_set ([string $default = 'default'])
static string get_fallback_template_set ([string $default = 'default'])
static mixed get_template_config (string $template_set_id, string $setting, [mixed $default = NULL], [boolean $live_config = FALSE])
Template Template (string $template_set_id)
void append (array|string $tpl_var, [mixed $value = NULL], [boolean $merge = FALSE])
void append_by_ref (string $tpl_var,  &$value, [boolean $merge = FALSE], mixed $value)
string apply_template (string $filepath)
void assign (array|string $tpl_var, [mixed $value = NULL])
void assign_by_ref (string $tpl_var,  &$value, mixed $value)
void display (string $file)
string fetch (string $file)
string fetch_external_stylesheet_links (mixed $sheets)
boolean find_and_cache_plugin_template_file (string $plugin, string $file, [string $template_set_id = ''])
array get_alternative_stylesheets ([boolean $full_path = FALSE])
array get_javascript_includes ([boolean $full_path = FALSE])
object The get_rendering_template_engine_object (string $filename)
array get_stylesheets ([boolean $full_path = FALSE])
object The get_template_engine_subclass ([string $template_set_id = ''])
mixed get_template_file_path (string $filename)
mixed get_template_vars ([string $varname = NULL])
void header (mixed $headers)
void set_up_template (string $template_set_id)
Variables
string $fallback_template_dir = '' (line 87)

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

string $fallback_template_engine = '' (line 96)

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

string $fallback_template_set_id = '' (line 78)

The fall-back template ID

array $other_template_engine_objects = array() (line 122)

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.

string $template_dir = '' (line 62)

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

string $template_engine = '' (line 70)

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

mixed $template_file_cache = array() (line 111)

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

string $template_set_id = '' (line 53)

The template ID

Methods
static method cache_template_file_hierarchy (line 543)

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 (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

static array cache_template_file_hierarchy ([boolean $regenerate_cache = FALSE], [array $additional_files = array()])
  • 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).
static method calculate_template_file_directory (line 324)

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

  • return: The relative template path (based off of SM_PATH)
static string calculate_template_file_directory (string $template_set_id)
  • string $template_set_id: The template ID from which to build the directory path
static method calculate_template_images_directory (line 342)

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

  • return: The relative images path (based off of SM_PATH)
static string calculate_template_images_directory (string $template_set_id)
  • string $template_set_id: The template ID from which to build the directory path
static method catalog_template_files (line 632)

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
static mixed catalog_template_files (string $template_set_id, [array $file_list = array()], [string $directory = ''])
  • 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.
static method construct_template (line 157)

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
static object The construct_template (string $template_set_id)
  • string $template_set_id: the template ID
static method get_default_template_set (line 259)

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.
static string get_default_template_set ([string $default = 'default'])
  • string $default: The template set ID to use if the default setting cannot be found in SM config (optional; defaults to "default").
static method get_fallback_template_set (line 224)

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.
static string get_fallback_template_set ([string $default = 'default'])
  • string $default: The template set ID to use if the fallback setting cannot be found in SM config (optional; defaults to "default").
static method get_template_config (line 429)

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.
static mixed get_template_config (string $template_set_id, string $setting, [mixed $default = NULL], [boolean $live_config = FALSE])
  • 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.
Constructor Template (line 132)

Constructor

Please do not call directly. Use Template::construct_template().

Template Template (string $template_set_id)
  • string $template_set_id: the template ID
append (line 1338)

Appends values to template variables

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

void append (array|string $tpl_var, [mixed $value = NULL], [boolean $merge = FALSE])
  • 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

Redefined in descendants as:
append_by_ref (line 1360)

Appends values to template variables by reference

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

void append_by_ref (string $tpl_var,  &$value, [boolean $merge = FALSE], mixed $value)
  • string $tpl_var: the template variable name
  • mixed $value: the referenced 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
  • &$value

Redefined in descendants as:
apply_template (line 1377)

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 apply_template (string $filepath)
  • string $filepath: The full file path to the template to be applied

Redefined in descendants as:
assign (line 1272)

Assigns values to template variables

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

void assign (array|string $tpl_var, [mixed $value = NULL])
  • array|string $tpl_var: the template variable name(s)
  • mixed $value: the value to assign

Redefined in descendants as:
assign_by_ref (line 1287)

Assigns values to template variables by reference

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

void assign_by_ref (string $tpl_var,  &$value, mixed $value)
  • string $tpl_var: the template variable name
  • mixed $value: the referenced value to assign
  • &$value

Redefined in descendants as:
clear_all_assign (line 1297)

Clears the values of all assigned varaiables.

void clear_all_assign ()

Redefined in descendants as:
display (line 1204)

Display the template

void display (string $file)
  • string $file: The template file to use
fetch (line 1219)

Applies the template and returns the resultant content string.

  • return: The template contents after applying the given template
string fetch (string $file)
  • string $file: The template file to use
fetch_external_stylesheet_links (line 1130)

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.
string fetch_external_stylesheet_links (mixed $sheets)
  • mixed $sheets: List of the desired stylesheets (file path to be used in stylesheet href attribute) to output (or single stylesheet file path).
fetch_right_to_left_stylesheet_link (line 1181)

Generate a link to the right-to-left stylesheet for

this template set by getting the "rtl.css" file from this template set, its parent (or grandparent, etc.) template set, the fall-back template set, or finally, fall back to SquirrelMail's own "rtl.css" if need be.

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

  • return: The stylesheet link as it should be sent to the browser.
string fetch_right_to_left_stylesheet_link ()
fetch_standard_stylesheet_links (line 1101)

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.
string fetch_standard_stylesheet_links ()
find_and_cache_plugin_template_file (line 729)

Look for a template file in a plugin; add to template file cache if found.

The file is searched for in the following order:

  • A directory for the current template set within the plugin: SM_PATH/plugins/<plugin name>/templates/<template name>/
  • In a directory for one of the current template set's ancestor (inherited) template sets within the plugin: SM_PATH/plugins/<plugin name>/templates/<parent template name>/
  • In a directory for the fallback template set within the plugin: SM_PATH/plugins/<plugin name>/templates/<fallback template name>/

  • return: TRUE if the template file was found, FALSE otherwise.
boolean find_and_cache_plugin_template_file (string $plugin, string $file, [string $template_set_id = ''])
  • string $plugin: The name of the plugin
  • string $file: The name of the template file
  • string $template_set_id: The ID of the template for which to start looking for the file (optional; default is current template set ID).
get_alternative_stylesheets (line 1002)

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.
array get_alternative_stylesheets ([boolean $full_path = FALSE])
  • 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)
get_fallback_template_file_directory (line 382)

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).
string get_fallback_template_file_directory ()
get_fallback_template_set_id (line 367)

Return the template ID for the fallback template set.

  • return: The ID of the fallback template set.
string get_fallback_template_set_id ()
get_javascript_includes (line 945)

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.
array get_javascript_includes ([boolean $full_path = FALSE])
  • 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)
get_rendering_template_engine_object (line 876)

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.
object The get_rendering_template_engine_object (string $filename)
  • string $filename: The name of the template file,
get_stylesheets (line 1052)

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.
array get_stylesheets ([boolean $full_path = FALSE])
  • 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)
get_template_engine_subclass (line 289)

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

  • return: Template subclass object for the template engine.
object The get_template_engine_subclass ([string $template_set_id = ''])
  • 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).
get_template_file_directory (line 355)

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).
string get_template_file_directory ()
get_template_file_path (line 819)

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.
mixed get_template_file_path (string $filename)
  • 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.
get_template_vars (line 1316)

Returns assigned variable value(s).

  • return: Desired single variable value or list of all assigned variable values.
mixed get_template_vars ([string $varname = NULL])
  • 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)

Redefined in descendants as:
header (line 1155)

Send HTTP header(s) to browser.

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

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

Set up internal attributes

This method does most of the work for setting up newly constructed objects.

void set_up_template (string $template_set_id)
  • string $template_set_id: the template ID

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