The Core framework is an event-based framework, which means that all requests must be done in the form of events. Events can be used to request actions or to request the display of a particular view or page. For each possible event that the application can receive, there must be a corresponding Event Handler.
The Event handlers are the elements in charge of performing the actual actions of the application. They are responsible for calling the appropriate models, pass any parameters necessary and invoke specific methods to accomplish different tasks. They also serve the purpose of isolating the model from the environment specific to the web application, such as HTTP-specific scopes (i.e. form / url), ColdFusion environment scopes (session, client, application), etc.
Event handlers are implemented as CFCs that follow certain specifications:
- All event handlers must be located within the "handlers" directory.
- Must extend eventHandler.cfc
- Event handler actions that can be called by the application controller must be exposed as public methods.
Because all event handlers extend eventHandler.cfc, they have access to a collection of functions that allow an event handler to perform tasks such as affecting the flow of the application, setting or changing the view and layout used, setting and retrieving values from the request scope, and setting system messages to be displayed on the view.
Most of the time an event handler will need to pass values to be used on a view. To do this use the function setValue(), any data element set using this function will be available within the view by referring to the request.requestState structure and then the proper key.
Warning: The controller also uses the requestState structure to store values used for the inner workings of the application. The shared keys are: event, view, model, and layout. To maintain the proper encapsulation these keys should not be set directly using setValue() and should be managed using the appropriate functions provided by the event handler.
The following table provides all functions available to any event handler. These functions are inherited from eventHandler.cfc
| Method Name | Description |
| setNextEvent() | Reloads the page and executes the requested event |
| setView() / getView() | Setter and getter for current view |
| setEvent() / getEvent() | Setter and getter for current event |
| setLayout() / getLayout() | Setter and getter for current layout |
| setModule() / getModule() | Setter and getter for current external module |
| redirect() | Facade for cflocation |
| throw() | Facade for cfthrow |
| dump() | Facade for cfdump |
| abort() | Facade for cfabort |
| getValue() | Retrieves a value from the request collection. If there is no variable with the given name, then returns the second argument as default |
| setValue() | Sets a value on the request collection. Views can access these values later by referring to the request.requestState structure. |
| getSetting() | Retrieves an application setting loaded from the config.xml.cfm file. These settings are stored on the Application scope. |
| setMessage() | Sets a System Message to be displayed on the view or layout. These messages are persistent across page redirects, but may only be displayed once. Messages are displayed on the view or layout by including the template includes/message.cfm |
| getService() | Returns the stored instance of the requested application service. See Application Services. |
To call an event handler, the browser request must include the variable "event" which takes as a value the name of the event handler CFC and the method to execute in dot notation. For example to call the event doLogin on the event handler ehGeneral.cfc, the HTTP request must have the form:
index.cfm?event=ehGeneral.doLogin
Additionally, the variable may also be passed as a form variable. For example:
< form name="frm" method="post" action="index.cfm" >
< input type="hidden" name="event" value="ehGeneral.doLogin" / >
...
< / form >
To call an event handler located in an external module use the format:
module.handler.event
Where module is the name of the folder within the location of the modules directory, handler is the CFC containing the event handler and event is the name of the method in the CFC that will handle the event.