Event Handlers

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.

CFCs

Event handlers are implemented as CFCs that are responsible for handling requests coming into the application from either a local source (like form, URL or REST) or a remote source (like Flex, Air or SOAP). These event handlers carry the task of controlling your application flow, calling business logic, preparing a display to a user and more.

Info: 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 directive

Handler Actions

Every method in this event handler controller that has an access of public is automatically exposed as a runnable event in ColdBox and will be auto-registered for you. That means there is no extra configuration or XML logic to define them. By convention they become alive once you create them and clients can request them. In ColdBox terms, each of these event handler methods are referred to as actions. ColdBox captures an incoming variable called event (from the form, URL or remote scopes) and uses it to execute the correct event handler and action method.

So what about private functions? You can still use them in your application as local helpers to a handler object or can be called across handlers via a nice function called runEvent() that we will explore later.

Default Action: index()

The default action of ANY handlers is the method index(). If you try to execute an event handler without defining an action, ColdBox will execute the default action instead.

Danger : Event Handlers are not to be used to write business logic. They should be light and fluffy!

rc : A reference to the request collection inside of the request context object

prc : A reference to the private request collection inside of the request context object

Note The rc and prc references each method receives are sent for convenience so that you can interact with the structures instead of through the event object's methods. Interacting with structures over methods is much more performant.

The request context object has tons of methods to help you in setting and getting variables from one layer to another, getting request metadata, rendering RESTful content, setting HTTP headers, and more. It is your information superhighway for specific requests. Remember that the API Docs are your best friend!