ColdBox Request Context Decorator Guide

Introduction

In order for you to continue with this guide, I will assume that you are already familiar with ColdBox's request collection. In Summary, ColdBox uses a request collection data structure where all variables can be stored and shared among a user's execution request. The Request Collection is a central repository of information that is refreshed on every user request with the request's information. This is how data gets moved around from event handlers to views and layouts to plugins and anything running inside of the framework. The object containing the request collection is the request context object found at coldbox.system.beans.requestContext (See API).

This object contains several methods to help you get values, set values, set views, layouts, get the current event, and much more. However, it is bound to the framework release and as we all know, each application is different in requirements and architecture. Thus, we have the application of the Decorator Pattern to our request context, in order to help developers program to their needs. So what does this mean? Plain and simply, you can decorate the ColdBox request context object with one of your own. You can extend the functionality to the specifics of the software you are building. You are not modifying the framework code base or will screw up your application. You are simply building on top of what ColdBox offers you.

"A decorator pattern allows new/additional behavior to be added to an existing method of an object dynamically." by wikipedia

Decorator Design Pattern Diagram

For what can I use them

• You can use the request context decorator to add extra functionality to a request object.
• These new functionalities can be specific to your application and architectural needs.'
• Have different contexts for different protocols
• and much much more.

How does it work

The very first step to do is to create your own request context decorator component. You can see in the diagram below the coldbox request context design pattern.

You will basically create a component and make it inherit from coldbox.system.beans.requestContextDecorator this is to provide all the functionality of an original request context decorator. Once you have done this, you will create a configure method that you can use for custom configuration when the request context gets created by the framework. Then it’s up to you to add your own methods or override the original request context methods. (See API). In order to access the original request context, you will use the provided method called: getRequestContext().

IMPORTANT The decorated request context has its own instance data that can be different than the original context (as of version 2.5.2). So please interact with the original context only if you need the original request data.

Sample Custom Request Context Decorator Declaration

In the sample below, you can see a custom request context declaration and a configure method. In this example, the configure method will trim all simple values that are found in the request collection.

<cfcomponent name="myRequestContext"
                         hint="This is a simple custom request context"
                         output="false"
                         extends="coldbox.system.beans.requestContextDecorator">
        
        <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 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>

</cfcomponent>

Sample Method Decoration

Below is a simple method decoration for the getValue() method. This sample basically trims any simple results as it returns them and also returns an empty variable 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 via original object, else return blank
                if( valueExists(arguments.name) ){
                        originalValue = getValue(argumentCollection=arguments);
                        //check if simple
                        if( isSimpleValue(originalValue) ){
                                originalValue = trim(originalValue);
                        }
                }
                
                return originalValue;
        </cfscript>
</cffunction>

As you can see from the code above, the possibilities to change behavior are endless. It is up to your specific requirements and it’s easy!!

How to declare it

The last step in this guide is to show you how to actually declare your decorator in your ColdBox configuration file. Look at the sample snippet below:

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

You need to create a new setting element with the following name attribute RequestContextDecorator? and with a value of the instantiation path for the component.

That's it, nothing more to it. Plain as day.

Conclusion

As you can see from this guide, constructing ColdBox Request Context Decorators are very very easy. You have a pre-defined structure that you need to implement and an easy setting to configure. You now have a great way to expand on your request requirements and add additional functionality without modifying the framework. The possibilities are endless with this feature. Enjoy!!