Revision as of 03:47, 11 July 2013

Introduction

The Caching Template Library is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

• Compiles templates to PHP code for enhanced page load speeds.
• Adds logic processing to the templates.
• Ability to specify multiple locations to search for templates.

Compiles Templates to PHP code

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in this forum message.

Logic Processing

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

Multiple Template Source Paths

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Benefits

Benefits of the Caching Template Library include:

• It is extremely fast.
• It is efficient since the PHP parser does the dirty work.
• No template parsing overhead, only compiles once.
• It is smart about recompiling only the template files that have changed.
• The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
• It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
• Built-in caching support.
• Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

Developer Information

VERSION CHECKS

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

TEMPLATE_OPTIONS

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

'path_cache' (required)

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

'path_prefixes' (required)

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

• the root of your themes directories ($_CONF['path_html']/layout).
• the root of your plugins directory ($_CONF['path']/plugins).
• the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

'unknowns' (optional)

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual.

'force_unknowns' (optional)

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

'default_vars' (optional)

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

• 'site_url' ⇒ $_CONF['site_url']
• 'site_admin_url' ⇒ $_CONF['site_admin_url']
• 'layout_url' ⇒ $_CONF['layout_url']
• 'XHTML' ⇒ XHTML

'incl_phpself_header' (optional)

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
    die ('This file can not be used on its own.');
} ?>

'cache_by_language' (optional)

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

'hook' (optional)

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

TEMPLATE->set_root()