Working With Event Handlers

Search…
Event handlers are the controller layer in ColdBox and is what you will be executing via the URLor a FORMpost. All event handlers are singletons, which means they are cached for the duration of the application, so always remember to var scope your variables in your functions.
Tip: For development we highly encourage you to turn handler caching off or you will have to reinit the application in every request, which is annoying. Open the config/ColdBox.cfc and look for the coldbox.handlerCaching setting.
config/Coldbox.cfc
1
/**
2
 * Development environment
3
 */
4
function development() {
5
    coldbox.customErrorTemplate = "/coldbox/system/exceptions/Whoops.cfm"; // interactive bug report
6
    coldbox.handlerCaching = false;
7
    coldbox.handlersIndexAutoReload = true;
8
    coldbox.eventCaching = false;
9
    coldbox.viewCaching = false;
10
}
Copied!
Once you started the server in the previous section and opened the browser, the default event got executed which maps to an event handler CFC (controller) handlers/main.cfc and the method/action in that CFC called index(). Go open the handlers/main.cfc and let's explore the code.
Handler Code
1
component extends="coldbox.system.EventHandler" {
2
​
3
    /**
4
     * Default Action
5
     */
6
    function index( event, rc, prc ) {
7
        prc.welcomeMessage = "Welcome to ColdBox!";
8
        event.setView( "main/index" );
9
    }
10
​
11
    /**
12
     * Produce some restfulf data
13
     */
14
    function data( event, rc, prc ) {
15
        return [
16
            { "id" : createUUID(), name : "Luis" },
17
            { "id" : createUUID(), name : "JOe" },
18
            { "id" : createUUID(), name : "Bob" },
19
            { "id" : createUUID(), name : "Darth" }
20
        ];
21
    }
22
​
23
    /**
24
     * Relocation example
25
     */
26
    function doSomething( event, rc, prc ) {
27
        relocate( "main.index" );
28
    }
29
​
30
    /************************************** IMPLICIT ACTIONS *********************************************/
31
​
32
    function onAppInit( event, rc, prc ) {
33
    }
34
​
35
    function onRequestStart( event, rc, prc ) {
36
    }
37
​
38
    function onRequestEnd( event, rc, prc ) {
39
    }
40
​
41
    function onSessionStart( event, rc, prc ) {
42
    }
43
​
44
    function onSessionEnd( event, rc, prc ) {
45
        var sessionScope     = event.getValue( "sessionReference" );
46
        var applicationScope = event.getValue( "applicationReference" );
47
    }
48
​
49
    function onException( event, rc, prc ) {
50
        event.setHTTPHeader( statusCode = 500 );
51
        // Grab Exception From private request collection, placed by ColdBox Exception Handling
52
        var exception = prc.exception;
53
        // Place exception handler below:
54
    }
55
​
56
}
Copied!
Every action in ColdBox 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)
This line event.setView( "main/index" ) told ColdBox to render a view back to the user found in views/main/index.cfm using a default layout, which by convention is called Main.cfm which can be found in the layouts folder.
Executing Events
We have now seen how to add handlers via CommandBox using the coldbox create handler command and also execute them by convention by leveraging the following URL pattern:
1
http://localhost:{port}/folder/handler/action
2
http://localhost:{port}/handler/action
3
http://localhost:{port}/handler
Copied!
Also remember, that if no action is defined in the incoming URL then the default action of index will be used.
Remember that the URL mappings support in ColdBox is what allows you to execute events in such a way from the URL. These are controlled by your application router: config/Router.cfc
Working With Incoming Data
Now, let's open the handler we created before called handlers/hello.cfc and add some public and private variables to it so our views can render the variables.
1
function index( event, rc, prc ){
2
    // param an incoming variable.
3
    event.paramValue( "name", "nobody" );
4
    // set a private variable
5
    prc.when = dateFormat( now(), "full" );
6
    // set the view to render
7
    event.setView( "hello/index" );
8
}
Copied!
Let's open the view now: views/hello/index.cfm and change it to this:
1
<cfoutput>
2
<p>Hello #encodeForHTML( rc.name )#, today is #prc.when#</p>
3
</cfoutput>
Copied!
Please note that we used the ColdFusion function encodeForHTML() (https://cfdocs.org/encodeforhtml) on the public variable. Why? Because you can never trust the client and what they send, make sure you use the built-in ColdFusion encoding functions in order to avoid XSS hacks or worse on incoming public (rc) variables.
If you execute the event now: http://localhost:{port}/hello/index you will see a message of Hello nobody.
Now change the incoming URL to this: http://localhost:{port}/hello/index?name=ColdBox and you will see a message of Hello ColdBox.
Tip: Please see the layouts and views section for in-depth information about them.
Linking Events Together
Adding A Layout
Last modified 9mo ago
Copy link
Edit on GitHub
Contents
Handler Code
Executing Events
Working With Incoming Data