Compatibility Guide for ColdBox 2.0.0
Affects: Event handlers, custom plugins, layouts and views.
It might seem at first that you need to change a lot of things for this release, but believe me they are worth it. This in preparation to the new event model that I have been planning and it opens up a whole new world. Plus, you get faster execution and more features than before. Just as a side note, it took me about 20 minutes to update all the samples. So NO EXCUSES. That is why there are search and replace features on IDE's.
Please also look at the examples in the samples gallery as they will show you usage in action.
Anatomy of a new Event Handler Init Method
The new init method for an event handler is totally OPTIONAL like in 1.1.0. If you would like to implement an init method for your handler, then it is up to you. However, you will need two lines of code in order for the method to execute properly. Look below at example:
<cffunction name="init" access="public" returntype="ehGeneral" output="false"> <cfargument name="controller" type="any" required="yes"> <cfscript> super.init(arguments.controller); //Any Code you like below return this; </cfscript> </cffunction> OR <cffunction name="init" access="public" returntype="ehGeneral" output="false"> <cfargument name="controller" type="any" required="yes"> <cfset super.init(arguments.controller)> <cfreturn this> </cffunction>
Anatomy of a new Event Handler Method
The only difference with a pre 2.0.0 handler is the addition of an argument to the method. Each method will receive the request context object named as Event, this is the new event bus. You will then have to use the methods explained below from the request context object.
NOTE: The name of the argument received is Event of type coldbox.system.beans.requestContext
<cffunction name="{Method Name}" access="public" returntype="void" output="false"> <cfargument name="Event" type="coldbox.system.beans.requestContext"> </cffunction>
PreHandler and PostHandler methods
This is a new addition to ColdBox. You can now declare these two methods in your event handler cfc: PreHandler and PostHandler. If you declare this methods in your cfc, then ColdBox will execute them at their specific event junctions: PreHandler will execute before the requested event and PostHandler will execute after the requested event.
Example:
<cffunction name="preHandler" output="false" returntype="void" access="public"> <cfscript> //Execute any pre-event code here. Like AOP logging, etc. </cfscript> </cffunction> <cffunction name="postHandler" output="false" returntype="void" access="public"> <cfscript> //Execute any post-event code here. Like AJAX serialization, etc. </cfscript> </cffunction>
How to retrieve the Request Context Object
However, you also have a second alternative, which is to retrieve the request context from the request service. This is useful for when calling private methods inside the handlers. You can either pass the request context object to the private method or let the private method retrieve it. Below is the code on how to retrieve the request context object from within a method or plugin.
<cfset var Event = controller.getRequestService().getContext()>
ColdBox offers alternatives
If you use cfeclipse, then these steps will be much simpler. I have created two new snippets for this step.
- Event Handler Method - Will create a blank method with the new format (Quick Key: ehm)
- Event Handler Request Context Argument - Will create the request context argument (Quick key: ehrc)
Internal Method Calling
If you had in your code some internal method calling like to private methods or other events, you will need to update the code to pass in the request context object or retrieve it from the method via the requestService just as it is shown above.
Example:
If you want to pass the context then: Before: <cfset doThisForme()> Now: <cfset doThisForme(Event)> Else, use the retrieval method, shown above. </cffunction>
You do not need to do anything if you used the runEvent() method because the framework does the request Event injenction. I usually use RunEvent?() than method calls.
Methods
The following methods will now be found in the request context object, they used to exist in every plugin and handler. However, due to 2.0.0's new request bus, they will have to be extracted from this new object. Please migrate your code in your event handlers, custom plugins, views and layouts to the following standards. This is where Copy And Paste comes really handy.
Request Methods
| What I used To Do | What I need to Do''' |
| getCurrentView() | Event.getCurrentView() |
| getCurrentLayout() | Event.getCurrentLayout() |
| getCurrentEvent() | Event.getCurrentEvent() |
| overrideEvent() | Event.overrideEvent() |
| paramValue() | Event.paramValue() |
| getValue() or rc. | Event.getValue() |
| setValue() or rc. | Event.setValue() |
| valueExists() | Event.valueExists() |
| removeValue() | Event.removeValue() |
| getCollection() | Event.getCollection() |
| setView() | Event.setView() |
| setLayout() | Event.setLayout() |
See CFC API for more in detail information.
New Request Context (Request Collection) Methods
The request context has now some new extra methods that you can use in your applications to interact with the request collection.
- setCollection( newCollection ) - replaces the entire collection with a new structure.
- collectionAppend( newStructure , overwrite [default=false] ) - appends a structure to the collection, with overwrite or not.
- getSize() - Retrieves the size of the collection in Items.
- clearCollection() - Clears the entire collection
See CFC API for more in detail information.
RC Scope is now Deprecated
If you were using the 'RC' scope in your applications, the RC scope is now deprecated. However, since it is much simpler to write and saves time, you can still leave your code intact. All you need to do is var scope it and use code similar to the one below:
The var scoping is using within methods. You do not need to use the var scope if you will use this technique in layouts and views. Thus, the alternative code:
FOR EVENT HANDLERS AND PLUGINS <cfset var rc = Event.getCollection()> or FOR VIEWS/LAYOUTS <cfset rc = Event.getCollection()> or FOR EVENT HANDLERS AND PLUGINS USING CFSCRIPT <cfscript> var rc = Event.getCollection(); </cfscript>
That is it my friends. The only difference due to the new bus is that the 'rc' scope must be var scoped and pointing to the request collection from the request Context object.
The following are the new eclipse snippets:
- Local Request Collection Reference - Creates the code above (Quick Key: rc)
- Local Request Collection Reference cfscript - Creates the code above in cfcsript format (Quick Key: rcs)
- External Request Collection Reference - Creates the code below (Quick Key: rce)
Changes in 2.0.0 as Facade Methods for Plugins and Event Handlers
The following methods have now become facade methods to the real deal. You can still call them as they are or with the new syntax. This is compatible with 1.1.0 and below. You have to write whatever you feel comfortable with.
See CFC API for more in detail information.
Plugin Interactions
Below are the two methods used to interact with plugins.
| Facade Method | Full Syntax Call |
| getPlugin() | controller.getPlugin() or getController().getPlugin() |
| getMyPlugin() | controller.getMyPlugin() or getController().getMyPlugin() |
Event Interactions
Below are the methods that interact with running and relocating to other events.
| Facade Method | Full Syntax Call |
| setNextEvent() | controller.setNextEvent() or getController().setNextEvent() |
| runEvent() | controller.runEvent() or getController().runEvent() |
Framework/Application Settings Interactions
Below are the methods that interact with the framework and application settings.
| Facade Method | Full Syntax Call |
| getSetting() | controller.getSetting() or getController().getSetting() |
| setSetting() | controller.setSetting() or getController().setSetting() |
| settingExists | controller.settingExists() or getController().settingExists() |
| getSettingStructure() | controller.getSettingStructure() or getController().getSettingStructure() |
This is it for this guide. If you have any questions, comments or concerns, please mail them to info@coldboxframework.com or visit the forums at http://www.luismajano.com/forums and post your concerns there.
