Request Context Guide

  1. Request Context Guide
    1. Overview
    2. How does it work?
    3. The event object
    4. Getting a reference to the collection
    5. What can I do with it?
    6. Most Commonly Used Methods
    7. Current request Metadata Methods
    8. Extending The Request Context
    9. Summary

Overview

ColdBox uses a data structure called the request collection to store the incoming FORM/URL/REMOTE variables and model a user's request. This collection lives inside of an object called Request Context. This object will become your best friend. A key important note about the collection is that this is how data gets moved around from event handlers to views and layouts to plugins and anything running inside of the framework.

As you can see from the diagram above, the request collection lives in the request scope and can be accessed from every single part of the framework's life cycle. Therefore, there is one contract and way on how to handle FORM/URL/REMOTE and any other kind of variables. You can consider the request collection to be sort of a super information highway that is unique per request. You will interact with it to get/set values that any part of a request's lifecycle will interact with it. The ColdBox debugger even traces for you how this data structure changes as events are fired during a request.

How does it work?

The framework on every request will capture the FORM/URL scopes or any remote variables and append them to a single structure called the request collection that lives inside of an object called the Request Context that is discussed below. This will make it much easier for you to have access to variables, since you will no longer be scoping them. It also encapsulates any other scopes you would like to merge into the collection. Another important aspect of the request context is that it also contains several metadata and utility methods that you can use to build your applications. Some of these methods are covered below, but the best place to learn about all of its methods is to read the API.

Note: FORM variables take precedence

The event object

What is this event object? Well, the event object is the name of the request context object as it is received by any part of the framework. It was called event in order to be a standard as it exists in all frameworks. The cfc that is used is coldbox.system.beans.requestContext. So when you have an event handler method receiving the request context object you will see the following: 

<cffunction name="myEvent" access="public" returnType="void" output="false">
  <cfargument name="event" type="coldbox.system.beans.requestContext">

</cffunction>

So to summarize, the event object's type is coldbox.system.beans.requestContext. This request context object contains an internal data structure called the request collection and you can interact with it via the object's methods or even get a reference to the entire collection in order to interact with it.

Getting a reference to the collection

In order to use the collection as a normal structure, you must first ask the event object to give you its reference and you do this by calling the getCollection() method: 

<cfset var rc = event.getCollection()>

<!--- Get members just like a structure --->
<cfset rc.myName = "Luis">
<cfset rc.myName = rc.myName & " Majano">

What can I do with it?

The event object has a plethora of methods to help you deal with a request:

  • Getting a reference to the collection
  • Appending structures to the collection
  • Removing values from the collection
  • Paraming values in the collection (Similar to cfparam)
  • Getting values from the collection
  • Setting values into the collection
  • Getting metadata about a request, such as the current executing event, handler, action, layouts, view, and much more.
  • Determining a coldbox proxy request
  • Determining if you are in SES mode
  • Building links for you
  • So much more.

For an in detail view of the request context object, please visit the API

Most Commonly Used Methods

Below you can see a listing of the mostly used methods in the request context object:

  • buildLink(string linkto, [boolean translate], [boolean ssl], [string baseURL]) : Build a link in SES or non SES mode.
  • clearCollection() : Clears the entire collection
  • collectionAppend(struct,overwrite) : Append a collection overwriting or not
  • getCollection() : Get a reference to the collection
  • getEventName() : The event name in use in the application (e.g. do, event, fa)
  • getSelf() : Returns index.cfm?event=
  • getValue(keyname, defaultValue) : get a value
  • getTrimValue(keyname, defaultValue) : get a value trimmed
  • getSESBaseURL() : Get the base ses url string.
  • isProxyRequest() : flag if the request is an incoming proxy request
  • isSES() : flag if ses is turned on
  • noRender(boolean) : flag that tells the framework to not render any html, just process and silently stop.
  • overrideEvent() : Override the event in the collection
  • paramValue() : param a value in the collection
  • removeValue() : remove a value
  • setValue(keyname, value) : set a value
  • setLayout(layout) : Set the layout to use for this request
  • setView(name,nolayout,cache,cachetimeout,cachelastaccesstimeout) : Used to set a view to render
  • showDebugPanel(boolean) : Sets whether the ColdBox debugging panel will be rendered or not.
  • valueExists() : Checks if a value exists in the collection.

Some Samples: 

//Get a reference
<cfset var rc = event.getCollection()>

//test if this is an MVC request or a remote request
<cfif event.isProxyRequest()>
  <cfset event.setValue('message', 'We are in proxy mode right now')>
</cfif>

//param a variable called page
<cfset event.paramValue('page',1)>
//then just use it
<cfset event.setValue('link','index.cfm?page=#rc.page#')>

//get a value with a default value
<cfset event.setvalue('link','index.cfm?page=#event.getValue('page',1)#')>

//Set the view to render
<cfset event.setView('homepage')>

//Set the view to render with no layout
<cfset event.setView('homepage',true)>

//set the view to render with caching stuff
<cfset event.setview(name='homepage',cache='true',cacheTimeout='30')>

//override a layout
<cfset event.setLayout('Layout.Ajax')>

//check if a value does not exists
<cfif not event.valueExists('username')>

</cfif>

//Don't show the debug panel for this request
<cfset event.showDebugPanel(false)>

//Tell the framework to stop processing gracefully, no renderings
<cfset event.noRender()>

//Build a link
<form action="#event.buildLink('user.save')#" method="post">

</form>

Current request Metadata Methods

  • getCurrentAction() : Get the current execution action (method)
  • getCurrentEvent() : Get's the current incoming event, full syntax.
  • getCurrentHandler() : Get the handler or handler/package path.
  • getCurrentLayout() : Get the current set layout for the view to render.
  • getCurrentView() : Get the current set view
  • getDebugpanelFlag() : Get's the boolean flag if the ColdBox debugger panel will be rendered.
  • getDefaultLayout() : Get the name of the default layout.
  • getDefaultView() : Get the name of the default view.

Extending The Request Context

One key feature about ColdBox is its flexibility. Every application is different and unique. Therefore, the request context might not do exactly what you need and if you needed to modify it, well you would have to modify the framework core files and that is NOT a good idea. Therefore, the decorator pattern came to our rescue and you can decorate the request context by using a request context decorator object. With this object you can decorate some or all of the methods in the request context provided to you by the framework. You can even add more functionality to it. How, well, for that you need to read the Request Context Decorator Guide.

Summary

You will be surprised at how many useful methods the event object contains. So I highly suggest you read the CFC API and study it. You will find tons of methods that will make your development life easier. Don't only read this guide and play with it, read also the CFC docs, they provide a wealth of information also.