A Look at Event Handlers - ColdBox Series Part 3

In my last post, we set up a base ColdBox application using the Application Template. So now we have a basic application that welcomes us to ColdBox. Not very useful.

So let's look at our Event Handlers and see if we can get them to do something more interesting.

What is an Event?

As I understand it, an event is an Object that is dispatched by the controller (ColdBox) and passed to the event handler when a request for the event is made. In ColdBox, the event object itself is of type coldbox.system.beans.requestContext and comes with a lot of built it methods and properties, plus it holds the request collection which:

...is a central repository of information that is refreshed on every user request with the request's information. This is how data gets moved around from event handlers to views and layouts to plugins and anything running inside of the framework and in the MVC layers.

- From the ColdBox Website

So an end user makes a request for an event like this:

The controller (ColdBox), then receives this request and create a event object (requestContext) and dispatches it to the event handler. The event handler in this case is the method getAllLists() inside of lists.cfc which is inside of the /handlers folder. In other words, it calls the getAllLists() method and passes in the event object: getAllLists(event)

The event handler, then receives the event object and can add or remove data using the built in event methods, like getCollection(), getValue() and setValue(). The event handler can then dispatch another event, or call a view for display (passing along the event object for both).

One important thing to note, any POST or GET requests sent to ColdBox are added to the Request Collection inside of the event object. So in our event handlers, we will never be accessing the FORM or URL variables directly. Their values are automatically placed in the Event Object's Request Collection.

For more on events, event handling and the RequestContext object, check here:

• How ColdBox Works
• Event Handler Guide
• Request Lifecycle
• Request Context Guide

Event Handlers

Which brings us to general.cfc. General.cfc is a regular old ColdBox event handler, and we do not "have" to use it. Personally, I don't like the name general, but that is a matter of preference. To keep things simple, we will leave the name the way it is.

Here is the default code for general.cfc

So here we have two event handler methods, index() and doSomething(). All doSomething() does is call index() using the setNextEvent() method, so let's delete it right now.

Now, let's look at the index() handler. Since the index() method is inside of the general.cfc file, we would request the event like this:

So when the request is made, ColdBox passes the event object (request context) to the event handler method, which accepts it as an argument.

Then it adds a value called "welcomeMessage" to the event object with this line:

Then it calls for a view (which we will look at in just a moment) named "home":

This will show the view to the end user. We can look at the view by looking in the /views directory that was part of the Application Template. It is at /views/home.cfm

Here is what the home.cfm looks like:

In the <h1> tag we get the welcome message that we created in the event handler by calling event.getValue("welcomeMessage"). Then the view calls the getSetting() method to get some settings out of the coldbox.xml file, which we will look at in my next post.

Pretty simple, huh?

Views

Well, let's go to the page in our browser and see what is actually getting rendered. There is a lot of debugging crap in there, but here is the important part:

Looks like valid XHTML to me. But where did all that other code come from? It came from our default layout. Which you will find in the /layouts directory. It is called Layout.Main.cfm. We will discuss layouts more in another post, I just wanted you to understand where that code is coming from.

Modifying our Event Handler

Our index() handler method will change to:

And our view will change to:

I have deleted the "welcomeMessage" value and created a "pageTitle" value instead, I have also added a "today" value and inserted a value using the Now() function.

In our view I have replaced the getValue() call for the "welcomeMessage" value and asked for the "pageTitle" value instead. And I have replace all of those getSetting() calls with a getValue() call for the "today" value and formatted it with the DateFormat() function.

Conclusion