Welcome to another installment of WordPress Wednesday!
Today’s topic is: Turning WordPress Shortcodes into ESI Blocks
If you’ve ever used ESI blocks before on your WordPress site, you know that they allow you to cache your content in an incredibly flexible way. We’ve talked before about ESI, and as part of that conversation we showed you how you could use ESI to cache widgets separately from the pages on which they appear.
For example, you can set your entire site to be cached for a week, but set your ESI widgets to expire after only 12 hours, if they have time-sensitive content. Or you can set your widgets to contain privately cached content, even when the rest of the page is cached publicly. This latter scenario is especially useful in WooCommerce and other shopping sites. Be sure to read that blog post for the whole story about how ESI and ESI widgets work.
Using ESI Shortcodes
This ability to define a different set of parameters for caching widget content is so useful. It’s only natural to consider other WP constructs that could be made better with ESI. The “shortcode” is one such construct.
As of LSCWP v2.8, ESI shortcodes are now supported. This allows you to cache the contents of the shortcode in a different way than you’ve cached the rest of the page.
If you have a myeventlist shortcode, for example, and it inserts a list of upcoming events into your page, you might use it like this:
[myeventlist month="December" year="2018"]
In its most basic form, an ESI shortcode is written exactly like the original shortcode with an esi in front of it. So, to turn the myeventlist shortcode into an ESI block, you would instead write this:
[esi myeventlist month="December" year="2018"]
By default, shortcode contents are stored in public cache, and the TTL defaults to whatever value you have stored in LiteSpeed Cache > Settings > General > Default Public Cache TTL, but you can change that with a few parameters.
To store the shortcode contents in private cache for five minutes (or 300 seconds), you can say this:
[esi myeventlist month="December" year="2018" cache="private" ttl="300"]
TL;DR: To turn a shortcode into an ESI shortcode, write it this way:
[esi + original shortcode and its parameters + optional esi parameters + ]
If You Deactivate LSCache…
If, for some reason, you decide in the future to deactivate the LiteSpeed Cache plugin, please be aware that your ESI shortcodes will no longer work. You will need to manually replace all ESI shortcodes with their original versions.
In other words, you’d need to change
[esi myeventlist month="December" year="2018" cache="private" ttl="300"]
back to
[myeventlist month="December" year="2018"]
everywhere it appears.
Limitations
ESI shortcodes have one important limitation: while LiteSpeed Cache can easily cache your shortcode contents, it is not possible for LSCache to purge the shortcode contents on demand.
Shortcode ESI blocks will naturally expire when the TTL is reached, but a purge cannot be triggered by particular events. This makes sense, because LiteSpeed can’t know which occurrences should trigger a purge. Different shortcodes all have different events that render them out-of-date, and there’s no way for LiteSpeed to know what they are.
Using the example of the event listing plugin above, let’s say you use the following shortcode:
[esi myeventlist month="December" year="2018"]
This will cache the myeventlist block for the same length of time as your site’s default TTL. If someone edits an event before the TTL is reached, then the ESI block will, unfortunately, be out-of-date until it expires naturally.
There are two ways to handle this issue:
- Have the shortcode’s plugin author use our API to trigger a purge when block content changes.
- Use a very short TTL, and live with the possibility that contents may be briefly out-of-date.
Let’s look at these two options.
Get the Plugin Author Involved
If it’s important that the shortcode contents be purged by specific events, you can share this API call with the author of the shortcode’s plugin (just be sure to replace myeventlist with the actual name of the shortcode you want to purge:
method_exists( 'LiteSpeed_Cache_API', 'purge' ) && LiteSpeed_Cache_API::purge( 'esi.myeventlist' ) ;
LSCache uses a powerful tagging system, and all cached content is organized by one or more tags. Content that belongs to an ESI shortcode is tagged with esi.+shortcode-name. (In this example, that’s esi.myeventlist.)
The plugin author should use this method any time the contents of the shortcode change. This is the most precise way to keep the content in the shortcode up-to-date and accurately cached according to the shortcode’s own requirements.
Learn more about the LiteSpeed API on our wiki.
Do it Yourself
If it is not critical for the contents of the shortcode to have up-to-the-minute accuracy, then you can use the ttl parameter to cache the content for a short time. For example, if you can live with content that is an hour old, set ttl="3600". If you are thinking more along the lines of five minutes, set it to ttl="300".
While it is possible to set the content to not be cached at all ( ttl="0"), it is not recommended. Any time there is uncached content on a page, PHP must be invoked in order to generate that content. PHP uses valuable resources, and significantly slows down a page. It’s far better to cache your content for a small amount of time than not at all.
Do You Need ESI Shortcodes?
Shortcodes are used for a wide variety of functions, and ESI will not be necessary for every one. If the shortcode contains private content on a public page, it might benefit from ESI. If it contains quickly-changing content on an otherwise mostly-static page, then ESI might be a useful way to cache more flexibly.
—
Disclaimer: The information contained in this post is accurate for LSCWP v2.8.1 [release log]. If you are using a newer version of the plugin, some details may have changed. Please refer to our wiki for the latest!
Have some of your own ideas for future WordPress Wednesday topics? Leave us a comment!
We’ll be back soon with another installment. In the meantime, here are a few other things you can do:
- Subscribe to the WordPress Wednesday RSS feed
- Download LiteSpeed Cache for WordPress plugin
- Learn more about the plugin on our website
Leave a Reply