Basic Usage
The CE Cache “It” Tag
Although there are several tags to choose from, the one you will assuredly be using the most is the It tag. The It tag will intelligently decide whether or not to cache the tagdata (the text between the opening and closing tag) you feed it. If the data is not cached or has expired, the It tag will then process the data, cache it, and return it. However, if the data is already cached, it simply retrieves it and returns it to your template.
Here’s an example of the It tag in action:
{embed="includes/_header"}
{!-- pretend there is some code here --}
{embed="includes/_stockquotes"}
<h1>Articles</h1>
{exp:ce_nav:channel_entries channel="articles" limit="5"}
<h2>{title}</h2>
{body}
{/exp:ce_nav:channel_entries}
{!-- and some more code here --}
{embed="includes/_footer"}
{/exp:ce_cache:it}
The first time the page is accessed, the data will be processed and cached. For the next hour after the page is cached, the cached version will be returned, which means 2 embeds and at least one channel entries tag will not have to run every time the page is requested.
Global Vs. Non-global Caches
For many of the tags there is a global= parameter. This parameter makes it possible to have special global caches.
ExpressionEngine’s native tag caching is all in a non-global scope, meaning that each cache is tied to the current URL. This makes things simple, but it also gives up some ground on performance. For example, if you have a list of your latest blog posts in your site’s footer embed (or snippet), and have EE tag caching enabled on the Channel Entries tag (by setting the cache="yes" refresh="60" parameters), that tag will be processed and then cached over and over again for each URL that is visited. The caches will also expire at different intervals (as they will be cached for 60 minutes from the page visit). CE Cache provides a solution to this issue by allowing caches to be optionally specified in a global scope.
By setting global="yes" on the tags that have that parameter, you are instructing CE Cache to make the cached item (specified by the id= parameter), available site-wide. So for the footer example above, you could actually cache a footer site-wide for an hour by giving the parameters id="footer" global="yes" seconds="3600". Each page subsequently requesting the footer would then draw from the same cached “footer” item.
If the global parameter is not included, or set to "no", then the id specified for the CE Cache tag would be unique to the current page. If you set an id of "page" on each page, for example, it would store a cached item for “page” for each page. However, if you had the parameters global="yes" id="page" on every page, each page would be caching to the same global location.
Items are cached by id in their scope. This means it is possible to have an item named “example’ cached on a per-page (non-global) basis, and a globally cached item with the same name of “example”.
Cache Structure
CE Cache creates a hierarchy of cached items for each site and driver. This logical organization of cached data makes it incredibly easy to locate your cached items to manually delete them or to review their metadata and cached content. Take a look at the Control Panel View Items section for more details.
Partial Caching
If there are ever chunks of code inside your It or Save tags that you don’t want to cache, you have the ability to prevent only those sections from being cached.
To prevent content from being cached, you can use the Escape tag. Essentially, it protects your data from the parser, so that it will leave your content alone and prevent it from caching.
As an example, let’s pretend that your includes/_header template embed above has the following content:
<html>
<head>
<!-- pretend title, meta, styles, and scripts are here -->
</head>
<body>
<p>{if logged_in}Hello {username}{if:else}Please log in{/if}</p>
Caching the {logged_in} conditional output would be bad, as we want users to be greeted by their own username, and not the person’s username that was online when the cache was created. So let’s escape that content to prevent it from being cached:
<html>
<head>
<!-- pretend title, meta, styles, and scripts are here -->
</head>
<body>
{exp:ce_cache:escape}
<p>{if logged_in}Hello {username}{if:else}Please log in{/if}</p>
{/exp:ce_cache:escape}
Nesting Tags
It is perfectly acceptable to nest tags. When nesting tags, be sure to keep the tags unique by adding an extra tagpart, like this:
{!-- pretend there is some code here --}
{exp:ce_cache:escape}
{exp:ce_cache:it:nested id="sidenav" global="yes" seconds="0"}
{embed="includes/_sidenav"}
{/exp:ce_cache:it:nested}
{/exp:ce_cache:escape}
{!-- pretend there is some more code here --}
{/exp:ce_cache:it}
In the above example, we added the extra tagpart :nested to the opening and closing tag of the nested It tag. That tagpart is arbitrary, and doesn't need to be named :nested, as long as it is unique; we could have elected to name the extra tagpart :foo or :bar, etc. It is essential to have a unique tagpart so the ExpressionEngine® parser doesn’t confuse itself and break.
Dummy Driver
The dummy driver does nothing. This can be a good thing.
Sometimes, you will want to easily work with your content on a site or page, and disable caching. Changing the driver to 'dummy' (view the specific tag parameters or config settings for more details) will ensure that no caching will take place.