The controller is an implementation of the Front Controller design pattern. In the case of the framework this is implemented using the Application.cfc provided by ColdFusion. The controller's job is to intercept every request to the application, process any requested events and then select the appropriate view and layout for display.
The Controller is built as a generic component so that it can be reused by many applications without having to modify how it works. However, since it is implemented in the Application.cfc, some settings such as the application name must be set appropriately for each individual application.
Besides the standard application settings defined on the Application.cfc (clientManagement, sessionManagement, etc), there are a few framework-specific settings that should be modified on a per application basis:
| Setting | Description |
| this.defaultEvent | Name of the event to be executed when no event has been called. |
| this.defaultLayout |
Name of the layout to use. When a layout is defined, either by using this property or setting it programmatically on an event handler, the actual file that is rendered is the layout file, regardless of the actual page requested. If the layout property is blank, then no layout is applied and the page rendered is the actual page called. |
| this.topLevelErrorRecipient | Email address to which to send an email report when unhandled errors occur. Emails will only be sent if this property is not empty, and this.emailErrors is set to True. |
| this.topLevelErrorSender | Email address to use as sender for error reports. |
| this.emailErrors | This flag controls whether to send or not bug reports via email whenever an unhandled exception occurs. Emails will only be sent if this property is not empty, and this.emailErrors is set to True. |
| this.restartKey | Flag to control automatic reinitialization of the application. See RestartKey for more information. |
| this.configDoc | Name of the XML file used for additional configuration. If application does not require the use of application settings or services, then this may be left empty. The file must always be contained within the config directory of the application. |
| this.modulesPath | Relative path to indicate where the external modules are located. External modules are packages of views and eventhandlers that can be placed outside of the application directory. They can be used for organization of large applications, or to provide “pluggable” modularity to an application. |
When a request is first received by the application, it is first intercepted by the onRequestStart method in the Application.cfc. Here the request is processed, the application is initialized (if needed) and the requested event handler (if any) is executed. After the Controller finishes its execution, if the Layout property is not empty, the control is passed to the selected Layout Page. Otherwise, the control is passed to whatever page was requested originally on the HTTP request.
A Layout Page can be selected either by explicitly requesting it on the HTTP request using the layout parameter, or it may be set by the event handler using the setLayout() function. If the layout page has not been explicitly set, then the framework uses the default layout defined by the this.defaultLayout property on the Application.cfc. It is the responsibility of the layout page to actually invoke and display the selected view.
The following diagram illustrates the sequence of events and interactions between the different elements of the framework for any request coming from the browser. Please note that the onApplicationStart event is only executed when the application is first initialized.
From the previous diagram you may see that the controller calls some predefined methods on the ehGeneral.cfc event handler. This file must be present and must contain the methods onApplicationStart, onRequestStart and onRequestEnd. These methods must be defined even when the application does not require any specific actions to occur at those moments.
The controller also is responsible for reading and loading the Application Settings and the Application Services.
Application Initialization
A very important function of the controller is to initialize the application. The idea of application initialization is to provide a place to execute tasks that need to happen only at the beginning of the application lifecycle. The framework handles this by storing a flag on the Application scope indicating that the application has been initialized. Handling this at the framework level rather than at the ColdFusion engine level (via the onApplicationStart method of Application.cfc) allows to manually restarting the application if needed and for a better integration with the framework. When the application is initialized, the controller executes the following events in the given order:
- If a configuration document is provided (using the this.configDoc key) then:
- Load and parse configuration document
- Load application settings
- Load application services
- Execute ehGeneral.onApplicationStart()
- Flags application as initialized
- Updates the restartKey
To manually force the controller to restart the application use the resetApp=1 parameter on the URL.
Restart Key
When working with an application that is deployed into a cluster of servers, using the resetApp flag to restart the application on all servers becomes a difficult and cumbersome task. In this case the reinitialization request need to be send to each server on the cluster. Furthermore, if the application is still running, having only a few servers restarted while others are not, could create serious problems.
To address this situation you must use the restartKey. This is a string defined at the beginning of the application.cfc. The value of this string is hard coded into the application. At the beginning of each request the controller will read this key and compare it with a previously stored value on the Application scope. If the values are different then this will force a reset of the application on the current server (just like if we had sent a resetApp flag targeted to that unique server).
After the application is reset, then the new restartKey will be recorded on the application scope so that subsequent requests will not cause a reset of the application.
The value of the restartKey can be any arbitrary value. This value can only be set by explicitly declaring it on the Application.cfc.
Global Error Handling
The application controller also provides a mechanism for global error handling. When an exception occurs within the controller, or any other part of the application and it is not handled when it occurs, then it triggers the onError method of the Application.cfc.
The onError method is already implemented on the controller. The default behavior is to send an email with the exception details to the address defined in the this.topLevelErrorRecipient key. Additionally the application displays the content of the includes/error.cfm template, which contains a generic error message. This template can be modified to adapt to the look and feel of the application being developed.
Note: Emails will only be sent if this.topLevelErrorRecipient property is not empty, and this.emailErrors is set to True.
