Balancing Speed and Freshness: How to Cache Modx TV Output Wisely

Why TV Caching Matters

In Modx Revolution, Template Variables (TVs) let you store arbitrary data on a per‑resource basis—think custom fields, dynamic blocks, or localized strings. When a site has dozens of pages, rendering every TV on every request can become costly. The Cache TV Output setting and the per‑TV Cacheable flag exist to help you cache that output and shave milliseconds off each page load.

Common Pitfall: Stale Content

The most frequent problem is a TV marked as cacheable, its value changes, but the cached output stays in memory. Visitors keep seeing the old value until the cache is purged. This is especially dangerous for content that updates frequently, such as a news headline or a promotional banner.

Takeaway

Enable caching only when you can guarantee that the TV value will not change often, or you have a clear cache‑clearing strategy in place.

How Modx Handles TV Caching

• System setting: cache_tv_output (yes/no). When enabled, TV output is cached for all resources by default.
• TV setting: Each TV has a Cacheable checkbox. If checked, that TV’s output will be cached when the system setting is on.
• Snippet parameters: You can override caching on a per‑call basis with &cacheable=1 or &tvCacheable=1 inside a snippet call.

When a TV is cached, Modx stores the rendered string in the system cache keyed by the resource ID and TV name. Subsequent requests for the same resource fetch the string directly, bypassing the TV rendering engine.

Practical Example: Caching a Static Banner TV

Suppose you have a TV called promo_banner that holds HTML for a promotional banner. The banner changes only once a month.

1. Create the TV:
   • Navigate to Elements → Template Variables → New TV.
   • Set Name to promo_banner, Input Type to Rich Text.
   • Check Cacheable.
2. Assign the TV to a template:
   • Open the template used by your homepage.
   • Add [[*promo_banner]] where you want the banner to appear.
3. Verify system setting:
   • System → Configuration → System Settings → cache_tv_output → Yes.
4. Clear the cache after editing the TV:
   • In the Manager, click Clear Site Cache (or run the snippet: [[!clearCache]]).
   • Reload the homepage; the banner should display the new content.

Now every subsequent visit to the homepage loads the banner from the cache, saving the time it would take to render the Rich Text each time.

Fine‑Grained Control with Snippet Parameters

If you need to cache a TV in some contexts but not others, you can override the flag in a snippet call. For example, on a detail page you might want the banner to be dynamic based on user preferences:

[[*promo_banner:cacheable=`0`]]

This forces Modx to render the TV fresh on that page, ignoring the global and TV settings.

Trade‑Offs & Limitations

• Memory Footprint: Each cached TV output consumes space in the cache. On large sites with many resources and TVs, this can add up. Monitor modx_cache directory size or use the modx cache stats snippet.
• Stale Data Risk: As mentioned, if a TV changes without clearing the cache, users see outdated content. Automate cache clearing via the onTVChange event or set up a cron job that clears the cache when a TV is edited.
• Version Dependency: The Cacheable flag is respected only in Modx 2.8 and later. If you’re on an older release, the flag is ignored; upgrade before relying on it.
• Complex TV Types: TVs that render other snippets or use dynamic data (e.g., a list of recent posts) should rarely be cached, or you must ensure the snippet itself is cache‑aware.

Checking the Result

After setting up caching, confirm it works:

1. Open the page in a browser with developer tools.
2. Inspect the rendered HTML; TV placeholders should be replaced with static content.
3. Use the modx_debug snippet ([[!modxDebug]]) to see if the TV was fetched from cache.

Actionable Checklist

• Enable cache_tv_output in System Settings.
• Mark TVs that change infrequently as Cacheable.
• Use snippet parameters to override caching where needed.
• Clear the site cache after editing a TV.
• Monitor cache size and adjust maxCacheFileSize if necessary.

By balancing the TV Cacheable flag with a clear cache‑clearing strategy, you can enjoy the performance gains of caching without sacrificing content freshness.