What's New in 2.5.0

The major upgrades to the framework for this version are the following:

Interceptors

The main purpose of creating ColdBox interceptors is to increase functionality for applications and framework alike, without touching the core functionality, and thus encapsulating logic into separate objects. This pattern wraps itself around a request in specific execution points in which it can process, pre-process, post-process and redirect requests. These interceptors can also be stacked to form interceptor chains that can be executed implicitly. The order of declaration is very important. These stacked interceptor chains form a chain of separate, declaratively-deployable services to an existing web application or framework without incurring any changes to the main application or framework source code. This is a powerful feature that can help developers and framework contributors share and interact with their work.

For what can I use them

Below are just a few applications of ColdBox Interceptors:

• Security
• Event based Security
• Method Tracing
• AOP Interceptions
• Publisher/Consumer operations
• Implicit chain of events
• Content Appending or Pre-Pending
• View Manipulations
• Custom SES support
• Cache advices on insert and remove
• Much much more...

SES Pretty URL Support

Thanks to ColdCourse by Adam Fortuna, ColdBox now supports Rails Style pretty URL's (SES) out of the box via interceptors. ColdBox introduces the ses interceptor that will make your life much prettier. Just simple tell your configuration that you want to enable the ses interceptor, set the location of the routes configuration, and your are ready to roll! The base configuration also brings three pre-configured routes for you:

• /handler/action/id
• /handler/action
• /handler

You can also use full SES support via mod rewrite or ISAPI rewrite with the included rewrite rule to dispatch to the interceptor or use the /index.cfm/ style of routing. It is all up to you, so enjoy full SES support.

Request Context Decorator

ColdBox uses a request collection data structure where all variables can be stored and shared among a user's execution request. The Request Collection is a central repository of information that is refreshed on every user request with the request's information. This is how data gets moved around from event handlers to views and layouts to plugins and anything running inside of the framework. The object containing the request collection is the request context object. This object contains several methods to help you get values, set values, set views, layouts, get the current event, and much more. However, it is bound to the framework release and as we all know, each application is different in requirements and architecture. Thus, we have the application of the Decorator Pattern to our request context, in order to help developers program to their needs. So what does this mean? Plain and simply, you can decorate the ColdBox request context object with one of your own. You can extend the functionality to the specifics of the software you are building. You are not modifying the framework code base or will screw up your application. You are simply building on top of what ColdBox offers you.

For what can I use them

• You can use the request context decorator to add extra functionality to a request object.
• These new functionalities can be specific to your application and architectural needs.'
• Have different contexts for different protocols
• and much much more.

Caching Eviction Policies

The ColdBox cache now includes two eviction policies based on LFU (Least Frequently Used) and LRU (Least Recently Used). The default policy is LFU, but you can override it from your configuration file by setting the Eviction Policy element. What does this mean though?

• LFU : The item with the lowest usage gets purged
• LRU : The item that was used the longest ago gets purged.

New Cache Flag to Not use Default Last Access Timeouts

You can now tell the ColdBox cache to ignore default last access timeouts and just concentrate on object timespans.

View Caching

You can cache views in 2.5.0 by explicitly telling the framework to cache them via the event.setView() method. Below are the new arguments:

Method: event.setView() Arguments

• view : the view to render or cache
• nolayout [default=false] : Whether to render the view in a layout or not
• cache [default=false] : Cache or not the view.
• cacheTimeout [default=""] : The timeout of the view in cache
• cacheLastAccessTimeout [default=""] : The last access timeout before the view expires.

Once you set the view to render, the renderer plugin will detect the cache and cache the resulting HTML. So now every time that view is requested to be rendered by the renderer plugin, it will be retrieved from cache.

Ways to purge views:

• getPlugin('renderer').purgeView('view')
• getColdboxOCM().clearAllViews()

Event Caching

Event caching is extremely useful and easy to use. All you need to do is add several metadata arguments to the cffunction tag of your event and the framework will cache the output of the event. In other words, the event executes and produces output that the framework then caches. So the subsequent calls do not do any processing, but just output the content. Almost all of the entire lifecycle is skipped, the content is just delivered.

Cached Event Lifecycle

1. Event is trapped
2. URL action fwCache is verified, if it exists, incoming event is purged from cache.
3. preProcess Interception is executed
4. RequestStartHandler is executed
5. Cached content is retrieved and outputed.

Please be aware that an event can have several unique permutations depending on the incoming url parameters. Also, caching is application wide, not user wide. So be careful of not caching secure events or session based events. The way to set up an event for caching is on its cffunction declaration with the following extra arguments:

ATTRIBUTE	TYPE	DESCRIPTION
cache	boolean	A true or false will let the framework know whether to cache this event or not. The default is FALSE.
cachetimeout	numeric	The timeout of the event's output in minutes. This is an optional attribute and if it is not used, the framework defaults to the default object timeout in the cache settings. You can place a 0 in order to tell the framework to cache the event's output for the entire application timeout controlled by coldfusion, NOT GOOD. Always set a decent timeout for content.
cacheLastAccesstimeout	numeric	The last access timeout of the event's output in minutes. This is an optional attribute and if it is not used, the framework defaults to the default last access object timeout in the cache settings. This tells the framework that if the object has not been accessed in X amount of minutes, then purge it.

Here is an example of setting up an event for caching:

<cffunction name="dspBlog" access="public" returntype="void" output="false" cache="true" cacheTimeout="30">

Ways to purge events:

• URL Action fwCache
• getColdboxOCM().clearAllEvents([async=true])
• getColdboxOCM().clearEvent(eventSnippet,[queryString=""],[async=true])

ColdFusion 8 and BlueDragon 7

The core ColdBox code has been updated to assemble itself according to its CFML context to take advantage of the new features of ColdFusion 8 and BlueDragon 7.

• The logger plugin has been updated to use cfthread and is completely multi-threaded.
• The ColdBox cache now reaps and clears in a multi-threaded state by default, but you can still clear events and views synchronously if you wanted to.

ColdBox Proxy: Flex/Air/Remote Integration

The ColdBox proxy enables remote applications like Flex and AIR to communicate with ColdBox and provide an event model for those applications. This feature lets you create an event driven model that can easily be called from within any flex/air application. Not only that, but you can reinitialize the entire application, get settings, and yes, announce custom or core interceptions. You can create custom interceptor chains for your model that can be executed asynchronously when a user hits a save record button for example. You can create a Service Layer with built-in environmental settings, logging, error handling, event interception and chaining, you name it, the possibilities are endless.

Not only that, but this enables you to actually create two front ends using the same reusable ColdBox and model code. The code is the same, you create event handlers, you interact with a request collection, with core and custom plugins, but you don't set views or layouts because the framework is now a remote framework for your model. So what do you do, well, return data, arrays, xml, value objects. Anything, right from withing the event handlers or setup a configuration setting that tells the framework to always return the request collection.

Updated Debugging Panel

The debugging panel look and feel has been updated. The cache report has been updated to reflect event/view/interceptor caching. The cache panel also gives you a quick cache look, where you can click on an item in the cache report and it will dump it from cache.

New Plugins Convention

You can now have a custom directory for plugins right in your application root by convention. Just create a plugins directory right in your root alongside your handlers, views and layouts directory. Any plugin you place inside that directory will be usable via the getMyPlugin() method. You can use packages and it will take precedence over your external plugins setting from your configuration file.

Application.cfc Support

You now have full Application.cfc support which in turn adds the following implicit handlers:

• session start handler
• session end handler
• session start interception point
• session end interception point

The new bootstrapper allows for backwards compatibility with Application.cfm and index.cfm support, but a move towards Application.cfc is VERY RECOMMENDED

New Setting: HandlersExternalLocation

This new setting is for declaring external handlers to your application. This is a great way to share handlers between applications. You can create entire applications this way and just use one codebase. The handlers look like if they are part of your application. The only difference is that if there are two handlers with the same name, one local and one external, the local will take precedence. So please make sure your naming conventions are right on. Imagine, creating a blog and sharing it with three sites at the same time. You update the blog code and it get's updated in all three sites.

Custom Bug Report

A user can now configure via the configuration file a template to use for the emailing of bug reports.

Messagebox Plugin

The messagebox plugin has been reworked to full tableless code via css. The MessageboxStyleClass Setting has been deprecated in favor of the MessageboxStyleOverride boolean setting. You will now define your messagebox style in your own stylesheet and just tell the configuration file to user yours.

JavaLoader

The JavaLoader plugin has been updated to the latest release 0.5 by Mark Mandel

Request Collection Persistance via setNextEvent()

You can now persist variables across relocations by just appending a list of variables to the set next event method. Once the framework picks up the relocation it will restore the variables back to the request collection for usage.

setNextEvent(event='blog.entry',persist='entry,entry_id,rsspreference');

The persist argument will then be used to grab the variables from the request collection, place them in a flash session variable, relocate and then re-inflate them and delete them from the flash memory.

Tracer Method with Persistance

You can now use the tracing methods in the logger panel to trace messages to the debugging panel, but it will persist them across relocations. This is extremely useful for debugging. The tracer messages will be stored until they can be rendered. Once rendered, they are cleared.

Layout Inheritance for Folders

You can now declare a folder element withing a layout elemen in the configuration file and all the views contained within that folder will inherit the layout association!

<Layout file="Layout.details.cfm" name="details">
  <Folder>tags/navigation</Folder>
  <View>myView</View>
</Layout>

New Plugins: cookiestorage and applicationstorage

You now have two new facade plugins to the cookie and application scope. The cookie scope even converts complex data types like query, structs, and arrays to wddx and saves them seamlessly.

Utilities Plugin

The Utilities plugin was renamed from the fileUtilities plugin. It also contains two new super useful methods:

• toStruct : Convert the ColdBox syntax for structures into a struct. eg. { fname:luis, lname: majano}
• toArray : Convert the ColdBox syntax for arrays into arrays. eg. [ 1,2,3,4 ]

No Render

You can now tell the framework not to render anything. This is usually called from event handlers via the event object:

event.noRender();

This tells the framework, to just process and silently finish execution. No rendering is needed. Great for single way ajax calls.

Request Context Object - Event - New Methods

The request context object (event) has now more new methods on it:

getSelf()	Get the front controller plus event name combo. eg. index.cfm?event=
getCurrentHandler()	Retrieves the name of the current executing handler for the main event (works with packages). Example: event=blog.security.entry, this returns security
getCurrentAction()	Retrieves the name of action for the main event. Example: event=blog.entry, this return entry
getFolderLayouts()	Gets the folder-layouts structure
isNoRender()	Whether the no render flag has been set.
NoRender(boolean)	Tell the framework not to render any content.
isProxyRequest()	Tells you if this is a ColdBox proxy request

New method on Super Type: Relocate()

New facade method to cflocation to use withing your handlers/views/layouts/plugins and interceptors.

New cache metadata for plugins/handlers: cacheLastAccessTimeout

You can now use the attribute: cacheLastAccessTimeout to tell the framework when to purge.

Example:

<cfcomponent name="handler" output=false cache="True" cacheTimeout="30" cacheLastAccessTimeout="5">

XMLValidate Errors

If your configuration file does not validate with the framework's XSD file, it will now show you specific errors.