Use the standard CFML application events through the framework.
Application.cfcfile in the root of your Wheels site just includes the
wheels/functions.cfmfile, which in turn includes a lot of framework specific code, you may wonder what the best way is to use CFML's
onRequestStart, etc. functions.
While it's perfectly possible to add your code directly to the
wheels/functions.cfmfile, we certainly don't recommend it. If you add code in there, you both increase the risk of accidentally modifying how the framework functions, and you also make it a lot harder to upgrade to future versions of Wheels.
The general recommendation is to never touch any files in the wheels folder. OK, with that little warning out of the way, how does one go about using the CFML events?
The answer is to use the
eventsfolder. There is a file in there for every single event that CFML triggers. So if you want some code executed on application start for example, just place your code in
onapplicationstart.cfm, and Wheels will run it when your application starts.
If you look closely in the
eventsfolder, you will also notice that there are some custom files in there that do not match up with standard CFML events. The
onmaintenance.cfmfile is one example. Let's have a closer look at these.
onmaintenance.cfmfile is included when Wheels is set to maintenance mode. After the file is included,
cfabortis called by Wheels so no other code runs in this mode.
You can place a generic error message in the
onerror.cfmfile to be displayed to the users whenever your site throws an error.
If you need to access the error information here (for logging purposes, for example) it is available at
On Missing Template
onmissingtemplate.cfmfile works in a similar way as the error file above, but it gets called when a controller or action in your application could not be found.
Note: If you want to make sure that all browsers show your custom 404 page you need to make it larger than 512 bytes in size. Google Chrome, for example, will display a friendly help page of its own when the 404 page is less than 512 bytes.
Sometimes it's useful to add functions right in the
Application.cfcfile to make them available to all templates. To achieve the same thing in Wheels, you can place your functions in
Again, because there is no
Application.cfcfile for you to work with in Wheels, you have to find a suitable place to set application settings such as
SessionTimeout, ScriptProtect, SetClientCookies, and so on. These are usually set in the constructor area of an
Application.cfcfile. We recommend that you set them in the