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. Event handlers are responsible for controlling your application flow, calling business logic, preparing a display to a user and much more.

Locations

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 ColdBox Modules instead.

Tip: You can create packages or sub-folders inside of the handlers directory. This is encouraged on large applications so you can organize or package handlers logically to facilitate better maintenance and URL experience.

External Location

You can also declare a HandlersExternalLocation directive in your Configuration CFC. This will be a dot notation path or instantiation path where more external event handlers can be found.

coldbox.handlersExternalLocation  = "shared.myapp.handlers";

If an external event handler has the same name as an internal conventions event, the internal conventions event will take precedence.

Development Settings

By default, ColdBox will only scan for event handlers on startup. For development we highly encourage you leverage the following configuration directives:

// Rescan handlers on each request, turn OFF in production please
coldbox.handlersIndexAutoReload = true;
// Deactivate singleton caching of the handlers, turn ON in production pleaese
coldbox.handlerCaching = false;

Anatomy

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 URL mappings (Which we saw in the previous section).

Components

Main.cfc

component extends="coldbox.system.EventHandler"{

    /**
     * Default Action
     */
    function index( event, rc, prc ){
        prc.message = "Hello From ColdBox";
        event.setView( "main/index");
    }

    /**
     * Action returning complex data, converted to JSON automatically by ColdBox
     */
    function data( event, rc, prc ){
        var data = getInstance( "MyModel" ).getArray();
        return data; 
    }

}

You can also remove the inheritance from the CFC and WireBox will extend the coldbox.system.EventHandler for you using Virtual Inheritance.

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

Actions

They are composed of functions which are called actions that will always have the following signature:

function name( event, rc, prc )

Each action receives three arguments:

1. event - An object that models and is used to work with the current request (otherwise known as the Request Context)

2. rc - A struct that contains both URL/FORM variables (unsafe data)

3. 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.

component extends="coldbox.system.EventHandler"{

    function index( event, rc, prc ){
        return "<h1> Hi from handler land!</h1>";
    }

    function save( event, rc, prc ){
        getInstance( "MyService" ).save( rc );
        relocate( "users/list" );
    }

    function myData( event, rc, prc ){
        return ['coldbox', 'wirebox', 'cachebox', 'logbox'];
    }
}

Private Actions

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.

Composed Properties

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:)

Event Handler UML

• cachebox : A reference to the CacheBox library (coldbox.system.cache.CacheFactory)

• controller : A reference to the Application Controller (coldbox.system.web.Controller)

• flash: A flash memory object (coldbox.system.web.flash.AbstractFlashScope)

• logbox: A reference to the application LogBox (coldbox.system.logging.LogBox)

• log: A pre-configured logging logger object (coldbox.system.logging.Logger)

• wirebox : A reference to the application WireBox Injector (coldbox.system.ioc.Injector)

• $super: A reference to the virtual super class if using non-inheritance approach.