Tuskfish has separate systems for caching images and pages, which reduce load on the server by "saving" content that has been dynamically generated for repeat viewing. Page-level caching can be enabled or disabled via the site preferences.

Image cache

When you upload an image with a content object (the 'image' field on the data entry form) you should provide a high quality image at or slightly above the maximum size you ever expect to display it. Think of it as a master image; you will not use it directly in your site, but you can use it to make copies for different purposes.

Typically you will need to display this image at different sizes in different areas of your site. For example, as a thumbnail accompanying a content teaser on your home page, and at a larger size when the full description of the content is viewed.

When a page is requested, Tuskfish checks the image cache folder (site_root/cache) to see if thumbnails matching the dimensions specified in the template already exist. If so, those are inserted into the template, and if not, Tuskfish will generate a thumbnail and save it to the cache for re-use on subsequent page loads.

The size of thumbnails is actually specified in the theme/template files by making a call to an object's getCachedImage() method. In the example below a 300px wide thumbnail of an object's master image will be inserted into the template:

<img src="<?php echo $content->getCachedImage(300); ?>" alt="<?php echo $content->getCaption(); ?>" />

On another page you might want to display the same image at 600px wide, in which case you would use:

<img src="<?php echo $content->getCachedImage(600); ?>" alt="<?php echo $content->getCaption(); ?>" />

If you change the layout of your site later on you may need to display content images at different sizes. Simply change the size of the thumbnails specified in the relevant theme/template files and your site will automatically build new thumbnails and update itself. Cool, huh?

Page cache

The page caching system works on similar principles to the image caching system. When a page is requested the controller script first checks if a cached copy exists. If so the script returns the cached version and stops executing, and if not execution continues to make the page and save it in the cache for re-use.

Cached pages are stored in a different location to images, in trust_path/cache. This is to ensure that people can't directly access cached pages via their browser, in case a page has been marked offline.

The page cache is called from your controller script. To use it, you must first enable the cache in site preferences, and set some variables just after validating any parameters in the query string, as these are used to name/identify the cached file. The following example below is taken from index.php:

// Validate input parameters.
$cleanId = isset($_GET['id']) ? (int) $_GET['id'] : 0;
$cleanStart = isset($_GET['start']) ? (int) $_GET['start'] : 0;
$cleanTag = isset($_GET['tagId']) ? (int) $_GET['tagId'] : 0;

// Set cache parameters. Basename is just the name of this file, eg. 'index.php'.
$basename = basename(__FILE__);

// Validated query string parameters as array.
$cacheParameters = array('id' => $cleanId, 'start' => $cleanStart, 'tagId' => $cleanTag);

After setting this up, you should proceed to check if the requested content actually exists, is marked online and update view counters etc. Once you've handled all the administrivia make the actual call to the cache like this:

// Check if cached page is available.
$tfCache->checkCache($basename, $cacheParameters);

If a cached file exists, it will be output and your controller script will cease execution at that point. If there is no cached file, then your controller script will continue to execute and build the page. When execution reaches tfFooter.php at the bottom of your script, the page will be saved to the cache for re-use and then output to the browser:

// Write the contents of the buffer to the cache.
if ($tfPreference->enableCache && isset($basename)) {
    $tfCache->cachePage($basename, $cacheParameters, ob_get_contents());
}

You can clear the page cache by clicking the Flush cache link in the admin section of your site (it does not clear the image cache). The cache will automatically be flushed every time you add, edit or delete a content object, to ensure that your index pages always remain up to date. Note that the cache will not operate if $basename is not set. You should not cache back end administrative pages.