My First Interceptor

Introduction

This hands on guide will show you how to quickly create a ColdBox interceptor. If you are still not that familiar with ColdBox interceptors, I suggest you read the Interceptors Guide. This guide is just a quick hands on that will show you the following:

• How to declare your interceptor
• How to create your interceptor
• Creating some methods

How to declare your Interceptor

In order to use an interceptor you must first declare it on your ColdBox configuration file under the Interceptors element. Look below for the declaration. Just as a note, our interceptor takes in two properties:

• xmlFile : The interceptor will use this property to actually read in that specific file, parse it and place it on application settings under the variable name in the property below.
• varName : The name to use to save the parsed xml.

Now look at the declaration below

<Interceptors>
  <Interceptor class="model.interceptors.xmlInjector">
    <Property name="xmlFile">config/myCustomXML.xml</Property>
    <Property name="varName">myCustomXML</Property>
  </Interceptor>
</Interceptors>

Now, as a side note. We can use one property but a complex property, if we so desired.

<Interceptors>
  <Interceptor class="model.interceptors.xmlInjector">
    <Property name="propStruct">{ xmlFile:config/myCustomXML.xml, varName:myCustomXML }</Property>
  </Interceptor>
</Interceptors>

As you can see, both approaches work and you can have options on what to create as simple or complex properties.

Creating the interceptor

Below you will see the code needed to declare a ColdBox interceptor:

<cfcomponent name="xmlInjector"
        hint="This interceptor will read an xml file, parse it and inject it to the settings."
        output="false"
        extends="coldbox.system.interceptor">

</cfcomponent>

That's it. You have now declared an interceptor, it just needs to inherit from the base ColdBox base Interceptor.

Important Note: All Interceptors are cached by default in the !ColdBox cache. You can not use any cache metadata tags in Interceptors.

All interceptors will inherit all the methods found in the framework super type object, that let you tap into ColdBox. You can see a listing of those methods in the Live API. Below are the methods inherited from the base interceptor class:

method	returntype	description
configure	void	Used to configure your interceptor after instantiation
getProperties	struct	Get the entire properties structure
getProperty	any	Get a property by name
setProperty	void	Set a property in the properties structure
propertyExists	boolean	Returns if the property name sent in exists or not.

Creating Some Methods

So now lets start creating some cool methods. The first method we will create is the configure method.

The configure method

In our case, this method checks that all properties are set, set a custom property and throw errors.

<cffunction name="Configure" access="public" returntype="void" hint="This is the configuration method for your interceptors" output="false" >
<cfscript>
        var theFile = "";
        
        //verify the properties
        if ( not propertyExists('xmlFile') ){
                throw("The property xmlFile does not exist.");
        }
        if ( not propertyExists('varName') {
                throw("The property varName does not exist.");
        }
        
        //Get the File Path
        theFile = getController().getAppRootPath() & getProperty('xmlFile');
        
        if ( fileExists(theFile) ){
                //Save it in the properties
                setProperty('expandedXMLFile', theFile);
        }
        else{
                throw("The xml file: #thefile# does not exist. Please review your paths");
        }
        
</cfscript>
</cffunction>

As you can see from the code, you do some property tests, if all are successful and the file exists, then set the expanded path in the properties of the interceptor.

The afterConfigurationLoad method

Interceptors work by you implementing the core execution points, that you can find in the Interceptors Guide. Below we implement the afterConfigurationLoad method. This methods executes after the framework loads and the config file has been parsed and loaded.

<cffunction name="afterConfigurationLoad" access="public" returntype="void" hint="Executes after the framework and application configuration loads, but before the aspects get configured. " output="false" >
<!--- ************************************************************* --->
<cfargument name="event" required="true" type="coldbox.system.beans.requestContext" hint="The event object.">
<cfargument name="interceptData" required="true" type="struct" hint="interceptData of intercepted info.">
<!--- ************************************************************* --->
<cfscript>
//all properties set, just read in the xml file and parse it
var xmlDoc = "";

//read and parse
xmlDoc = XMLParse( getProperty('expandedXMLFile') );

//set in the application settings
getController().setSetting( getProperty('varName'), xmlDoc );

</cfscript>
</cffunction>

The method will be executed, and the interceptor will read and parse the xml file declared. Then inject it to the application settings as a variable using properties. Well, that's it folks. What a simple but an example that can be super useful when expanded.