In ColdBox 4 we have expanded the runEvent() method to allow you to add caching parameters so ColdBox can take care of caching output from events. This is a great way to accelerate the execution of widgets or viewlets within an application as it will execute them and cache them as needed. Here is the new signature for the runEvent() method.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
/*** Executes events with full life-cycle methods and returns the event results if any were returned.* @event The event string to execute, if nothing is passed we will execute the application's default event.* @prePostExempt If true, pre/post handlers will not be fired. Defaults to false* @private Execute a private event if set, else defaults to public events* @defaultEvent The flag that let's this service now if it is the default event running or not. USED BY THE FRAMEWORK ONLY* @eventArguments A collection of arguments to passthrough to the calling event handler method* @cache.hint Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.* @cacheTimeout.hint The time in minutes to cache the results* @cacheLastAccessTimeout.hint The time in minutes the results will be removed from cache if idle or requested* @cacheSuffix.hint The suffix to add into the cache entry for this event rendering* @cacheProvider.hint The provider to cache this event rendering in, defaults to 'template'*/function runEvent( event="", boolean prePostExempt=false, boolean private=false, boolean defaultEvent=false, struct eventArguments={}, boolean cache=false, cacheTimeout="", cacheLastAccessTimeout="", cacheSuffix="", cacheProvider="template"){ |
Here are the arguments of interest for caching:
cache: activate cachingcacheTimeout: the default timeout of the entrycacheLastAccessTimeout: the idle timeout of the entrycacheSuffix: A string suffix to incorporate into the cache key for uniquenesscacheProvider: The CacheBox region
The cache argument tells ColdBox to activate caching for the output of the event execution. It will execute the event with the passed in parameters and then cache the output of such execution (if any, if none then it does not cache anything). It will create a cache key composed of the event name, the cacheSuffix and the eventArguments structure. So please be aware of this so you don't have key collisions. By default, all cacheable entries will be stored in the template cache region of CacheBox and you can use many different cache methods to purge this area (See API Docs):
- clearAllEvents([any
async]) - clearEvent(any eventsnippet, [any queryString])
- clearEventMulti(any eventsnippets, [any queryString])
Here are some examples
1 2 3 4 5 6 7 8 |
<!--- Render with default cache timeouts --->#runEvent( event="widgets.users", cache=true )#<!--- Render with specific cache args --->#runEvent( event="widgets.users", cache=true, cacheTimeout=60 )#<!--- Render with specific event args --->#runEvent( event="widgets.users", eventArguments={ filter:true }, cache=true, cacheTimeout=60 )# |
Happy Caching!
Add Your Comment