Event Handlers
Last updated
Was this helpful?
Last updated
Was this helpful?
Event handlers are ColdBox's version of controllers in the MVC design pattern. So every time you hear "event handler", you are talking about a controller that can listen to external events or internal events in ColdBox. These event handlers carry the task of controlling your application flow, calling business logic, preparing a display to a user and much more.
If an external event handler has the same name as an internal conventions event, the internal conventions event will take precedence.
By default, ColdBox will only scan for event handlers on startup. For development we highly encourage you leverage the following configuration directives:
They are composed of functions which are called actions that will always have the following signature:
Each action receives three arguments:
event
- An object that models and is used to work with the current request
rc
- A struct that contains both URL/FORM
variables (unsafe data)
prc
- A secondary struct that is private only settable from within your application (safe data)
An action will usually do the following:
Set a view/layout to render
Return HTML
Return Complex Data which is converted to JSON by default
Relocate to another event/URL Route
The default action for all event handlers is called index()
. This means that when you execute an event, you can omit the index if you so desire.
So what about private
functions? Private functions are not executable from the outside world, but can be executed internally via a function available to all handlers called runEvent()
, which we will explore later.
It is imperative that you realize that there is a great object model behind every event handler controller that will enable you to do your work more efficiently. The following are the composed properties every event handler has in their variables
scope, you do not need to do anything to retrieve them, they are already there :)
controller : A reference to the Application Controller (coldbox.system.web.Controller
)
flash: A flash memory object (coldbox.system.web.flash.AbstractFlashScope
)
$super: A reference to the virtual super class if using non-inheritance approach.
All your handlers will go in the handlers folder of your application template. If you get to the point where your application needs even more decoupling and separation, please consider building instead.
You can also declare a HandlersExternalLocation
directive in your . This will be a dot notation path or instantiation path where more external event handlers can be found.
Event handlers are CFCs that will respond to FORM posts, HTTP requests and/or remote requests (like Flex,Air, SOAP, REST) via an incoming variables called event or by (Which we saw in the previous section).
You can also remove the inheritance from the CFC and WireBox will extend the coldbox.system.EventHandler
for you using .
Event Handlers are treated as singletons by ColdBox, so make sure you make them thread-safe and properly scoped. Persistence is controlled by the coldbox.handlerCaching
cachebox : A reference to the library (coldbox.system.cache.CacheFactory
)
logbox: A reference to the application (coldbox.system.logging.LogBox
)
log: A pre-configured logging (coldbox.system.logging.Logger
)
wirebox : A reference to the application (coldbox.system.ioc.Injector
)