My First Request Context Decorator

Introduction

In order to understand this quick hands on guide, you must first understand what a decorator is and how it applies to ColdBox. For that, please read the Request Context Decorator Guide. That guide will show you why use a decorator and how. This guide is just a quick hands on that will show you the following:

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

How to declare your decorator

In order for ColdBox to know that it must use a decorator it must be declared in your ColdBox configuration file as shown below:

<Setting name="RequestContextDecorator" value="model.myRequestContext" />

The value of the setting is the instantiation path of the object, just like if you where using the CreateObject?() method, so you can use mappings, paths, etc.

That's it!! What? You thought there was more to it. Well, no. You declare, and ColdBox uses.

How to create your decorator

The second step is to create the component in the path specified by the value in your setting. In this case its in model/myRequestContext.cfc. Below you can see my declaration:

<cfcomponent name="myRequestContext"
             hint="This is a simple custom request context"
             output="false"
             extends="coldbox.system.beans.requestContextDecorator">
        
       

</cfcomponent>

So all you need to create the request context is to actually make it inherit from the ColdBox base requestContextDecorator class. That's it, then you will have all the methods needed for your decorator to work.

Some special methods that you inherit for this decorator are:

getRequestContext()	This methods gives you the original request context object you have decorated
configure()	A pseudo-constructor method you can use to create your own configurations

IMPORTANT The state of your request context will now be on your decorated context. So changes have to be made to the decorator not the orginal context. The orginal context is there for decoration purposes only and for you to retrieve the original request data.

Creating some methods

Now that I have declared and constructed the shell for my decorator, I will create some methods.

The Configure method

You can create a special method called configure in your decorator that will be fired every time the context gets created. This is a great way to create a pseudo-constructor on your object. Look at mine below, in which I trim all the incoming variables in the context:

 <cffunction name="Configure" access="public" returntype="void" hint="This is the configuration method for your context as its created." output="false" >
        <cfset var key = "">
        
        <!--- Get the original collection via the original request context object --->
        <cfset var rc = getRequestContext().getCollection()>
        
        <!--- I will trim all of the request collection --->
        <cfloop collection="#rc#" item="key">
                        
                <!--- Trim only simple values --->
                <cfif isSimpleValue(rc[key])>
                        <cfset rc[key] = trim(rc[key])>
                </cfif>
                        
        </cfloop>
        <!--- Set the new collection --->
        <cfset setCollection(rc)>
</cffunction>

Is that cool or what. I have just trimmed all the variables that get captured by the framework into the request context.

getValue decorated

The method that I create next is the getValue method. This will actually decorate the original getValue method with the functionality of actually returning an empty value if the value doesn't exist.

<cffunction name="getValue" returntype="Any" access="Public" output="false">
<!--- ************************************************************* --->
<cfargument name="name"         type="string"   required="true">
<cfargument name="defaultValue" type="any"      required="false" default="NONE">
<!--- ************************************************************* --->
<cfscript>
        var originalValue = "";
        
        //Check if the value exists
        if( valueExists(arguments.name) ){
                //Get the original value
                originalValue = getValue(argumentCollection=arguments);
        }
        
        //Return either the value or an empty string.
        return originalValue;
</cfscript>
</cffunction>

Is that cool or what!! Well, we are not done yet, what if I want to create a method that is my original method, well, you can.

An extra method: getSESSelf()

This is a custom method that will be available in the event object anywhere in the app:

<cffunction name="getSESSelf" returntype="string" access="Public" output="false">
<cfscript>
var self = "index.cfm/";
        
self = self & getCurrentHandler() & "/" & getCurrentAction();
        
return self;
</cfscript>
</cffunction>

This basically constructs the following:

index.cfm/{handler}/{action}

Very useful when using on navigation:

<a href="#event.getSESSelf()#">My Link</a>

And that is it my folks, you have a working decorator.