Template Tags

{exp:speedy:fragment}

Fragment caching uses a tag pair to cache a specific block of content, as opposed to the entire page when using Static caching. You can put anything you want inside of a {exp:speedy:fragment} tag pair, including {embed}, {exp:channel:entries}, or any other ExpressionEngine tag.

The fragment tag does not currently work if using Twig or Blade templates when Coilpack is installed. However, static caching does. Twig has it's own caching built in. It is possible that Speedy will support the fragment tag for Twig and Blade in a future release.

Parameters

• disable="{if publisher:is_draft}yes|no{/if}" Disable caching if a condition is met. (Default: "")

• driver="dummy|file|redis|memcache|memcached" The name of the cache driver you want to use for this specific instance of the fragment cache tag. This will override the default global setting in your config.php file. If not defined, the global driver defined in $config['speedy_driver'] will be used. (Default: "")

• global="yes|no" Whether this item should be cached globally or not. Non-global items use the current url as part of their key. (Default: "no")

• key="featured_item"The key for the item cached in this tag pair. If this key is used for a non-expired cache item, the content of that item will be used instead of parsing the content of the tag. (Required when global="yes") (Default: "item")

• ttl="3600" The number of seconds before this cache item with expire. If left blank the default TTL (1 hour) will be used. Use ttl="0" to cache this item until the cache it broken. (Default: "")

• tags="apple|orange|etc" A pipe-separated list of tags to apply to this item. Tags can be used in the cache breaking settings. (Default: "")

• url_override="path/to/page"Override the url used as part of the key for non-global items. (Default: "")

• url_prefix="something"Add a prefix to the key. Useful for multi-lingual sites, e.g. url_prefix="{publisher:current_language_code}" (Default: "")

  • If using Publisher, and you are not displaying the default language segment in the URL, you may need a conditional similar to the url_prefix parameter: url_prefix="{if publisher:current_language_id != publisher:default_language_id}{publisher:current_lang_code}{/if}"

• parse="inward" This parameter is not specific to Speedy. It is available on all ExpressionEngine template tags. If you are having issues parsing a fragment that contains other {exp:module:function} tags (either first or third party), try adding parse="inward" to the fragment tag and it will likely resolve any parsing issues.

Example

{exp:speedy:fragment}

    ... content to be cached ...

{/exp:speedy:fragment}

Caching contents of channel:entries tags

When using the speedy:fragment tag pair with an channel:entries tag it is recommended to wrap the entire channel:entries tag pair with a speedy:fragmenttag.

If you attempt to add multiple speedy:fragment tags inside of a channel:entries tag to cache the output of custom fields separately, you may not get desired results. ExpressionEngine's parser pre-parses custom fields that are tag pairs, such as any Grid, Fluid, Relationship, or Bloqs field. Thus while the cache item may be created, it will not be used on output, ExpressionEngine will re-parse the contents of the speedy:fragment pair every time. For example:

Don't do this:

{exp:channel:entries}
    {title}
    
    {exp:speedy:fragment key="grid-contents"}
        {my_grid_field}
            ...
        {/my_grid_field}
    {/exp:speedy:fragment}
    
    {exp:speedy:fragment key="relationship-contents"}
        {my_relationship_field}
            ...
        {/my_relationship_field}
    {/exp:speedy:fragment}
    
    {exp:speedy:fragment key="bloqs-contents"}
        {my_bloqs_field}
            ...
        {/my_bloqs_field}
    {/exp:speedy:fragment}
    
{/exp:channel:entries}

Do this:

{exp:speedy:fragment key="entry-contents"}
    {exp:channel:entries}
        {title}
        
        {my_grid_field}
            ...
        {/my_grid_field}
    
        {my_relationship_field}
            ...
        {/my_relationship_field}
    
        {my_bloqs_field}
            ...
        {/my_bloqs_field}
    {/exp:channel:entries}
{/exp:speedy:fragment}

{exp:speedy:escape}

When using fragment caching, it may be desirable to prevent certain sections of the template that are inside your {exp:speedy:fragment} from being cached. ExpressionEngine will still parse the contents of an escape tag every page load.

Pre-escaping

Some template variables such as {segment_*} are always parsed before the module. For these tags we have implemented pre-escaping using a core extension.

To use pre-escaping, add a unique suffix to the tag.

Example

{exp:speedy:fragment}

    ... content to be cached ...

    {!-- Regular escape --}
    {exp:speedy:escape}
        {if logged_in}
            You are logged in
        {if:else}
            You are not logged in
        {/if}
    {/exp:speedy:escape}

    {!-- Pre-escape --}
    {exp:speedy:escape:foo}
        You are on the {segment_2} page
    {/exp:speedy:escape:foo}

    ... content to be cached ...

{/exp:speedy:fragment}

Template Layouts

Using ExpressionEngine's {layout} feature works as expected if you are using the Static cache driver, or Redis with static enabled, but if you are using fragment caching you'll need to cache your layout file as a separate global cache item, and escape the {layout:contents} tag. For example:

<head>
    <title>{layout:page_title}</title>
    
    {layout:some_meta_data}
</head>

{exp:speedy:fragment key="global-layout" global="yes"}
    <nav>
        <!-- global navigation -->
    </nav>
    
    {exp:speedy:escape}
        {layout:contents}
    {/exp:speedy:escape}

    <footer>
        <!-- global footer -->
    </footer>
{/exp:speedy:fragment}

Then inside your template:

{layout="layouts/main"}

{exp:speedy:fragment key="{segment_3}"}

   {exp:channel:entries url_title="{segment_3}"}
	
       {exp:speedy:escape}
		       {layout:set name="page_title"}{title}{/layout:set}
		       {layout:set name="some_meta_data"}Some value here{/layout:set}
       {/exp:speedy:escape}
       
       <!-- custom fields to render the page content -->

   {/exp:channel:entries}
   
{/exp:speedy:fragment}

This technique will result in an additional cached item for each layout that is globally cached. Custom layout variable tags (e.g. anything other than {layout:contents}) unfortunately can not be inside of an {exp:speedy:fragment} tag in your main layout file, which means you can't use fragment caching for the entirety of your layout file, but depending on your layout file you should be able to cache the majority of it. If you need to cache your entire layout file, then static caching may be a better strategy than fragment caching.

{speedy:set_ttl}

Added in v1.7.0

Dynamically set the TTL of a fragment or statically cached page. Note that in this example if you are iterating over multiple channel entries, only the last occurrence of the {speedy:set_ttl} tag will be used. The {speedy:set_ttl} tag pair will also accept values such as "1 week", "2 months", or even a timestamp by using the {expiration_date} variable from an entry.

{exp:channel:entries}
    {title}
    <!-- Using multiple set_ttl tag pairs is not recommend, these are just examples of the values it accepts -->
    {speedy:set_ttl}3600{/speedy:set_ttl} <!-- this will set the TTL to 3600 seconds-->
    {speedy:set_ttl}{expiration_date}{/speedy:set_ttl}
    {speedy:set_ttl}3 days{/speedy:set_ttl}
{/exp:channel:entries}

{speedy:add_tag}

Added in v1.7.0

Dynamically add tags to an {exp:speedy:fragment} tag pair or {exp:speedy:static}. For example:

{exp:speedy:fragment tags="foo|bar"}
    {exp:channel:entries}
        {title}
        {speedy:add_tag}{url_title}{/speedy:add_tag}
    {/exp:channel:entries}
{/exp:speedy:fragment}

{exp:speedy:clear}

Use this in your templates to clear specific cache items.

Parameters

• tags="apple|oranges" Clear one or more tags and all items cached with that tag.

• items="local/blog/footer|local/blog/header" clear one or more specfic cache items.