Using CFML Scopes in Mach II - Mach-II/Mach-II-Framework GitHub Wiki

1. Form and URL Variables
2. Application Variables
   • Setting Properties via the XML File
   • Setting Properties via Property.cfc
   • Application Scope and Application.cfc
3. Request Variables
4. Session Variables

Common CFML scopes such as application, session, request, form, and url, play an important role in CFML applications. When developing with Mach-II, best practices exist to guide you in terms of how these scopes should (or should not) be referenced throughout your applications.

As you may be aware, the event object is at the heart of every Mach-II request. One key piece of functionality that the event object offers is to bundle the form and url scopes into one convenient package (the event object itself). Once in the event object, all of your form and url variables are available wherever the event object is passed throughout the lifecycle of the request. This is very convenient behavior as you are no longer concerned whether a variable is in the form or url scope, as the variables in both scopes are made available as arguments within the event object.

To access an event object argument:

    <cfset myVar = event.getArg("varName") />

In Mach-II, application wide variables are defined as Mach-II properties in the mach-ii.xml configuration file. Once defined, these properties can be accessed from anywhere in the application simply by calling getProperty("myPropertyName").

Defining a property in mach-ii.xml

    <properties>
        <property name="dsn" value="myDsn" />
    </properties>

As you can see, adding simple name value pairs as application properties is very simple in Mach-II. With the 1.5 release, Mach-II introduced the ability to store complex data types including arrays, structs, and CFCs as application wide properties as well. For more information on working with complex data types as Mach-II properties, see this feature article by Matt Woodward.

For a complete explanation, please read our wiki entry on setting Setting Environment / Platform Specific Properties.

Mach-II properties are application wide and therefore properties are like the application scope. It is best practice to not use the application scope in Mach-II applications and use the properties.

Request scope variables in traditional CFML applications are likely to be event arguments in Mach-II applications. In addition to automatically bundling form and url variables together, Mach-II also makes it easy to add additional arguments into the event object on an "as-need" basis.

Within a .cfm template or CFC:

    <cfset event.setArg("argName", "arg value") />

Within the mach-ii.xml configuration file

    <event-handler event="myEvent" access="public">
        <event-arg name="pageTitle" value="This is my page title!" />
        <view-page name="myPage" contentArg="mainContent" />
        <execute subroutine="layoutPage" />
    </event-handler>

It is extremely common to encapsulate the access of session variables into a session facade CFC. For a complete review of this concept, check out the wiki entry on Using a Session Facade.