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.

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";

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

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; 
    }

}

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

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

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

Events are determined via a special variable that can be sent in via the FORM, URL, or REMOTELY called event. If no event is detected as an incoming variable, the framework will look in the configuration directives for the DefaultEvent and use that instead. If you did not set a DefaultEvent setting then the framework will use the following convention for you: main.index

Please note that ColdBox supports both normal variable routing and URL mapping routing, usually referred to as pretty URLs.

Event Syntax

In order to call them you will use the following event syntax notation format:

event={module:}{package.}{handler}{.action}

• no event : Default event by convention is main.index

• event={handler} : Default action method by convention is index()

• event={handler}.{action} : Explicit handler + action method

• event={package}.{handler}.{action} : Packaged notation

• event={module}:{package}.{handler}.{action} : Module Notation (See ColdBox Modules)

This looks very similar to a Java or CFC method call, example: String.getLength(), but without the parentheses. Once the event variable is set and detected by the framework, the framework will tokenize the event string to retrieve the CFC and action call to validate it against the internal registry of registered events. It then continues to instantiate the event handler CFC or retrieve it from cache, finally executing the event handler's action method.

Examples

// Call the users.cfc index() method
index.cfm?event=users.index
// Call the users.cfc index() method implicitly
index.cfm?event=users
// Call the users.cfc index() method via URL mappings
index.cfm/users/index
// Call the users.cfc index() method implicitly via URL mappings
index.cfm/users

The framework provides you with the relocate() method that you can use to relocate to other events thanks to the framework super type object, the grand daddy of all things ColdBox.

So always remember that you relocate via relocate() and if I asked you: "Where in the world does event handlers get this method from?", you need to answer: "From the super typed inheritance".

Views (Default Layout)

The event object is the object that will let you set the views that you want to render, so please explore its API in the CFC Docs. To quickly set a view to render, do the following:

The view name is the name of the template in the views directory without appending the .cfm. If the view is inside another directory, you would do this:

The views you set will use the default layout defined in your configuration file which by default is the layouts/Main.cfm

View With Custom Layouts

You can also use the setView(), setLayout() methods to tell the framework which view and layout combination to use:

Views With No Layout

You can also tell the framework to set a view for rendering by itself with no layout using the noLayout argument

setView() Arguments

Here are the arguments for the setView() method:

Cached Views

You can leverage the caching arguments in the setView() method in order to render and cache the output of the views once the framework renders it. These cached views will be stored in the template cache region, which you can retrieve or purge by talking to it: getCache( 'template' ).

View Arguments

Data can be passed from your handler to the view via rc or prc. If you want to pass data to a view without polluting rc and prc, you can pass it directly via the args parameter, much like a method call.

Access the data in the view like so:

No Rendering

If you don't want to, you don't have to. The framework gives you a method in the event object that you can use if this specific request should just terminate gracefully and not render anything at all. All you need to do is use the event object to call on the noRender() method and it will present to the user a lovely white page of death.