Tag-Based Caching (Block Cache)

Last Updated: Jun 8, 2021
documentation for the dotCMS Content Management System

The #dotcache directive allows you to wrap arbitrary blocks of html and velocity code in a time limited static cache. It can be used many times in a single page, template, container or content and can even be nested if needed. The #dotcache tag is intended to allow dotCMS web developers to fine tune the trade off of scalability vs. responsiveness in dotCMS pages and applications.


Page cache (Cache TTL property on the Page) always takes priority over Block cache.

So, when using Block cache on a Page, you should set the Cache TTL value on the Page to 0, and use Block Cache to control the caching of the slow regions of your Page.


#dotcache(String KEY,int TTL)
I am cached content or velocity
Timestamp: $date
KEYA unique identifier string for the content to be cached.
TTLThe Time To Live (in seconds) for contents in the block.
After the TTL has expired, contents in the block should be retrieved directly from the content store without accessing the block cache.

Key Values

The value of the KEY string is entirely in hands of the web developer and can be dynamically set based on other velocity variables. Careful thought should be given as to what key to use, since the key will determine how the content is cached based on whether or not the key is shared between pages, sessions, and users.

Some variables you can use to build your keys include:

VariableDescriptionCache Sharing
${CONTAINER_INODE}Container inodeAll pages which share the container.
$!{user.userId}User IDAll content accessed by the same user.
$!{host.inode}Host inodeAll users accessing the same host.
$!{HTMLPAGE_INODE}Page inodeAll content displayed on the same page.
$!{URLMapContent.inode}URLMap Content inodeAll content for the same URL Mapped content item.
$request.getRemoteServer()Visitor's IP addressAll requests from the same visitor.
$request.getHeader("User-Agent")Visitor's User AgentAll visitors using the (exact) same user agent (browser, device, etc.).
$request.getHeader("Accept-Language")Visitor's browser languageAll visitors who have selected the same browser language.
$session.getAttribute("com.dotmarketing.htmlpage.language")The visitor's selected languageAll visitors who have selected the same language in dotCMS.

TTL and Cache Invalidation

The TTL (Time To Live) parameter is an Integer, specified in seconds. dotCMS adds the TTL to the creation time of the cache entry and compares:

  • If the creation time + TTL >= now() the content will be returned from the block cache.
  • Otherwise the cache entry will be invalidated and the content will be fetched directly from the dotCMS content store.

TTL Example

  • 10:00 You hit a page with the following dotcache directive:
    #dotcache("mykey", 3600)
    • Result: First hit, cache miss.
      • The content is added to the cache with a create time of 10:00.
  • 10:30 You hit the page again:
    #dotcache("mykey", 3600)
    • Result: Cache hit.
      • The content is returned from the cache, because it is still within 3600 seconds of the create time of 10:00.
  • 10:35 You hit the page again, this time with the same key and a different TTL:
    #dotcache("mykey", 1800)
    • Result: Cache miss.
      • Content in the cache has a create time more than 1800 seconds ago. Cache entry is invalidated and content is re-fetched from the dotCMS content store and placed in the cache with a create time of 10:35.

URL Parameters

The block cache directive may also take two parameters via URL which change how the #dotcache regions on the page are handled:

URL ParameterDescription
?dotcache=noForce “no caching” of all content in #dotcache blocks on the page.
e.g., force a cache miss on all #dotcache blocks (but do not reset the TTL).
?dotcache=refreshForce all #dotcache entries to be invalidated;
This both forces a cache miss on all entries and resets the TTL for all cache entries.

These directives can be executed via any web browser on any page, by adding them to the end of the URL, e.g.


Invalidating the Cache (#dotcacheinvalidate)

The #dotcacheInvalidate directive allows you to programatically invalidate any item in the cache from velocity. This can be helpful when applications update pages or content and need the cache refreshed immediately.


#dotcacheinvalidate(String key)


  • The #dotcache directive is decoupled from the dotCMS publishing architecture by design.
    • Unlike the other caches in dotCMS, it does not try to respect changes to site and content as they are made; a #dotcache block will serve the cached content until the TTL time has expired.
    • Keep your content contributors in mind (and in the loop) when deploying the #dotcache directive around their content.
  • A #dotcache block will always serve live content and data while browsing sites from the dotCMS backend administration tool's Edit/Preview/Live modes.
    • Therefore testing of the block cache should always be done from the front end of a dotCMS web site.
    • In addition, Admin mode will always show you a dynamic view of the content, so you should always test caching while logged in as a non-Admin user.
  • Important: The system will take a few minutes to pick up a new #dotcache directive and store the new key.
    • So you may wish to wait a few minutes to test a new block cache after you have applied it to a certain portion of a page.

On this page