Request Context Guide

Overview

ColdBox uses a request collection data structure where all variables can be stored and shared among an every execution request. Below is my definition:

The Request Collection is a central repository of information that is refreshed on every user request with the request's information (FORM/URL). 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 request scope and can be accessed from every single part of the framework's pieces. Therefore, there is one contract and way on how to handle FORM/URL 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.

How does it work?

The framework on every request will capture the FORM and URL scopes and append them to a single structure called the request collection that lives inside of an object 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.

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. It was called event in order to be a standard as it exists in all frameworks. However, the coldfusion component 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 as 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 from:

• Getting a reference to the collection
• Appending structures to the collection
• Removing values from the collection
• Paraming values from the collection
• 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
• So much more.

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

Mostly Used Methods

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

• clearCollection() : Clears the entire collection
• collectionAppend(struct,overwrite) : Append a collection overwriting or not
• getCollection() : Get a reference to the collection
• getSize() : The number of objects in 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
• isEventCacheable() : if an event is about to be cached or is cached.
• isNoRender() : flag if the request will not render any html
• isProxyRequest() : flag if the request is an incoming proxy request
• 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
• valueExists() : Checks if a value exists in the collection.
• setValue(keyname, value) : set a value
• showDebugPanel(boolean) : Sets whether the ColdBox debugging panel will be rendered or not.

Current request Metadata Methods

• getCurrentAction() : Get the current execution action (method)
• getCurrentEvent() : Get's the current incoming even, 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.