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. Event handlers are responsible for 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:
rc
- A struct that contains both URL/FORM
variables (unsafe data)
prc
- A secondary struct that is private. This structure is only accessible from within your application (safe data)
An action will usually do one of 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 important to note that there is a pre-defined object model behind every event handler controller that will enable you to do your work more efficiently. The following are the automatically generated properties every event handler makes available in their variables
scope:)
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 be stored 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 RC variable 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
event
- An object that models and is used to work with the current request (otherwise known as the )
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
)