Although ANYTHING you could ever want to know about coldbox is definitely in its documentation, I find that it is still necessary sometimes to have to piece things together bit by bit..."...line upon line, line upon line; here a little, and there a little:...." as the prophet Isaiah said... in order to fully comprehend them. In this post I'd like to share what I have distilled from the docs regarding the subject of using interceptors and custom interception points in Coldbox.

The Scenario:  you are building your first Coldbox app and you decide that you want to generate your navigation from your database only after the user has authenticated (before that, they get no nav). How we retrieve and/or create our navigation isn't relevant to this post (I'll likely be sharing my navigation interceptor in another post), but WHEN and WHERE creation occurs IS, so allow me to break it on down as I have come to understand it.

If you weren't already aware, an interceptor in Coldbox is simply a CFC with methods that can be executed anywhere in the Coldbox request lifecycle, independent of the logic you already have "hard coded" to run for that event. In terms that we can all probably relate to, think of interceptors in EXACTLY the same way that you think of application.cfc. You know that code within that CFC will run "just because the file exists" and you don't have to explicitly call it in your app. Methods like  "onRequestStart" or "onRequestEnd"...their code automatically gets executed at specifically defined moments in the request's lifecycle simply by virtue of their name and the CFC they happen to live in. Same with a Coldbox Interceptor, except unlike application.cfc, you have to tell Coldbox that your interceptor exists first.

It's important at this point that we briefly talk about interception points in Coldbox. You know what "onSessionStart" is, you know what "onRequestEnd" is, you know what "onError" is, etc. ... well take a gander at "preRender". This is an interception point built in to Coldbox that "happens", or is announced, before content is rendered as viewable. (On a side note, there are a whole lot of OTHER interception points that exist natively in Coldbox; you should take the time to read through the list of them in the docs before you start developing.) In order to take advantage of "preRender" then and make something happen at that point, I have to do three things:

1. Create an interceptor CFC and drop it into my "interceptors" folder in my Coldbox app;
2. Create a method in that interceptor called "preRender";
3. Register my interceptor in Coldbox's "coldbox.xml.cfm" file so that the framework knows it exists.
how to register a custom interceptor...

Okay, I said in my scenario description that I only wanted my navigation created IF the user was authenticated. Of course you can guess that my "preRender" method does a check to see if that has occurred or not, and acts accordingly. But, what about the actual login event itself? If you trace the process, the user will be authenticated AFTER the preRender event, and so even though they have successfully logged in, will NOT see the navigation! Not kosher.

I dealt with this by using one of Coldbox's "Custom Interception Points". At first, it seemed like such a  foreign idea that little ol' me would have the power to add an interception point within the request lifecycle. After all, weren't things such as "onRequestStart" items that only the framework or the CF Server itself had the privilege of manipulating? But here's where the mystique of interception points, even those used in application.cfc, went away for me. (Hopefully you are familiar with the children's game "Red Light/Green Light", because my understanding and explanation of an interception point is based on it). An interception point is nothing more than a framework or CF Server playing a game of "red light/green light" with our app. The call to the app (http://myapp/?event=index) is the little kid, running forward like he was told to do. At certain points, though, the framework calls out "greenlight!", and any bit of your code that you had set up listening for "greenlight" (containing a method called "greenLight()") executes, right there and then, independent of the code associated with the event being called, and even before the request itself has completed. In my case, then, all I did was write a bit of code in my login process that called out "onLogin!" as soon as authentication occurred. I then added a method to my navigation interceptor called...what do you think? Yep, "onLogin", that made sure the navigation was available for the user at the end of the request. Here, then, are the steps to adding and using your own custom interception points in Coldbox:

1. Tell Coldbox that you would like to use an interception point called "onLogin", or "onLogout", or whatever you want to call it;
2. Add a line anywhere in any of your handlers (controllers) that ANNOUNCES your custom interception point;
3. Create one or more methods in any of your interceptors named the same as your custom interception point.

That's it! Here are some code snippets of where and how to do each of the three steps above:

1. In coldbox.xml.cfm, in the "Interceptors" section, add a line like the following:

3. In your interceptor(s), create a method like so:

Doug out