CFC variables and scope

CFCs interact with ColdFusion scopes and use local variables.

Note:

Components also have a Super keyword that is sometimes called a scope. For information on the Super keyword, see Using the Super keyword in Using CFCs effectively.

The This scope

The This scope is available within the CFC and is shared by all CFC methods. It is also available in the base component (if the CFC is a child component), on the page that instantiates the CFC, and all CFML pages included by the CFC.
Inside the CFC, you define and access This scope variables by using the prefix This, as in the following line:

<cfset This.color="green">

In the calling page, you can define and access CFC This scope variables by using the CFC instance name as the prefix. For example, if you create a CFC instance named car and, within the car CFC specify <cfset This.color="green">, a ColdFusion page that instantiates the CFC could refer to the component's color property as #car.color#.
Variable values in the This scope last as long as the CFC instance exists and, therefore, can persist between calls to methods of a CFC instance.

Note:

The This scope identifier works like the This keyword in JavaScript and ActionScript. CFCs do not follow the Java class model, and the This keyword behaves differently in ColdFusion than in Java. In Java, This is a private scope, whereas in ColdFusion, it is a public scope.

The Variables scope

The Variables scope in a CFC is private to the CFC. It includes variables defined in the CFC body (initialization or constructor code) and in the CFC methods. When you set Variables scope variables in the CFC, they cannot be seen by pages that invoke the CFC. 
The CFC Variables scope does not include any of the Variables scope variables that are declared or available in the page that instantiates or invokes the CFC. However, you can make the Variables scope of the page that invokes a CFC accessible to the CFC by passing Variables as an argument to the CFC method.
You set a Variables scope variable by assigning a value to a name that has the Variables prefix or no prefix.
Values in the Variables scope last as long as the CFC instance exists, and therefore can last between calls to CFC instance methods.
The Variables scope is available to included pages, and Variables scope variables that are declared in the included page are available in the component page.

Note:

The Variables scope is not the same as the function local scope, which makes variables private within a function. Always define function-local variables using the var keyword of the Local scope name.

Example: sharing the Variables scope

The following example shows how to make the Variables scope of the page that invokes a CFC accessible to the CFC by passing Variables as an argument to the CFC method. It also illustrates that the Variables scope is private to the CFC.
The following code is for the callGreetMe.cfm page:

<cfset Variables.MyName="Wilson">
<cfobject component="greetMe" name="myGreetings">
<cfoutput>
Before invoking the CFC, Variables.Myname is: #Variables.MyName#.<br>
Passing Variables scope to hello method. It returns: #myGreetings.hello(Variables.MyName)#.<br>
After invoking the CFC, Variables.Myname is: #Variables.MyName#.<br>
</cfoutput>
<cfinvoke component="greetMe" method="VarScopeInCfc">

The following code is for the greetMe CFC:

<cfcomponent>
<cfset Variables.MyName="Tuckerman">
<cffunction name="hello">
<cfargument name="Name" Required=true>
<cfset Variables.MyName="Hello " & Arguments.Name>
<cfreturn Variables.MyName>
</cffunction>
<cffunction name="VarScopeInCfc">
<cfoutput>Within the VarScopeInCfc method, Variables.MyName is: #variables.MyName#<br></cfoutput>
</cffunction>
</cfcomponent>

In this example, the callGreetMe.cfm page does the following:

  1. Sets the MyName variable in its Variables scope to Wilson.

  2. Displays the Variables.MyName value.

  3. Calls the  greetMe  CFC and passes its Variables scope as a parameter.

  4. Displays the value returned by the  greetMe  CFC.

  5. Displays the Variables.MyName value.

  6. Invokes the VarScopeInCfc method, which displays the value of Variables.MyName within the CFC.
    When you browse the  callGreetMe . cfm  page, the following appears:

Before invoking the CFC, Variables.Myname is: Wilson.
Passing Variables scope to hello method. It returns: Hello Wilson.
After invoking the CFC, Variables.Myname is: Wilson.
Within the VarScopeInCfc method, Variables.MyName is: Tuckerman

The Arguments scope

The Arguments scope exists only in a  method,  and is not available outside the method. The scope contains the variables that you passed into the method, including variables that you passed in the following ways:

  • As named attributes to the cfinvoke tag
  • In the cfargumentcollection attribute of the cfinvoke tag
  • In cfinvokeargument tags
  • As attributes or parameters passed into the method when the method is invoked as a web service, by Flash Remoting, as a direct URL, or by submitting a form
    You can access variables in the Arguments scope using structure notation (Arguments.variablename), or array notation (Arguments[1] or Arguments[" variablename "]).
    The Arguments scope does not persist between calls to CFC methods.
    Variables in the Arguments scope are available to pages included by the method.

Other variable scopes

A CFC shares the Form, URL, Request, CGI, Cookie, Client, Session, Application, Server, and Flash scopes with the calling page. Variables in these scopes are also available to all pages that are included by a CFC. These variables do not have any behavior that is specific to CFCs.

Function local variables

Variables that you declare with the Var keyword inside a  cffunction  tag or CFScript function definition are available only in the method in which they are defined, and only last from the time the method is invoked until it returns the result. You cannot use the Var keyword outside function definitions.

Note:

Always use the Var keyword or Local scope name on variables that are only used inside the function in which they are declared.

Define all function local variables at the top of the function definition, before any other CFML code; for example:

<cffunction ...>
<cfset Var testVariable = "this is a local variable">
<!--- Function code goes here. --->
<cfreturn myresult>
</cffunction>

Any arguments declared with the cfargument tag must appear before any variables defined with the cfset tag. You can also place any cfscript tag first and define variables that you declare with the Var keyword in the script.
Use function local variables if you place the CFC in a persistent scope such as the Session scope, and the function has data that must be freed when the function exits.
Local variables do not persist between calls to CFC methods.
Local variables are available to pages included by the method.

Static support for CFC

When objects are created from the same ColdFusion component, they each have their own distinct copies of instance variables. Sometimes, you want to have variables that are common to all objects. This is accomplished with the static modifier. Fields that have the "static" prefix in their declaration are called static fields or component variables. They are associated with the component, rather than with any object of that component.

The static feature can be disabled in a CFC using staticSupport = false flag as an attribute to CFC. The flag is true by default. Static support is only available to CFCs, not in CFM, but static access is allowed in a CFM.

Static support is available for the following:

Static block

Declare a static block that gets executed exactly once, when the component is first loaded.

Case1.cfc

component { 
    // instance constructor body 
    writedump("non static") 
    // static constructor body 
    static { 
        writeDump("static") 
    } 
}

Case1.cfm

<cfscript> 
    new Case1() 
    new Case1() 
</cfscript> 

Output

static non static non static

Static variables

When a variable is declared as static, then a single copy of the variable is created and shared among all objects at the component level.

Case2.cfc

component { 
    // static constructor body 
    static { 
        Static.counter = 0; 
    } 
    static.counter++; 
    writeDump(static.counter&" instances used so far"); 
} 

Case2.cfm

<cfscript> 
    new Case2() 
    new Case2() 
    new Case2() 
</cfscript> 

Output

1 instances used so far 2 instances used so far 3 instances used so far

Static methods

A Static method is declared using the static keyword. In a static method, you can use static or local scoped variables only. Methods declared as static have these restrictions:

  • Can only call other static methods.
  • Can only access static or local data.

Case3.cfc

component { 
    /** 
    * splits a full name in half 
    */ 
    public static function splitFullName(required string fullName) { 
        var arr=listToArray(fullName,"  "); 
        return {'lastname':arr[1],'firstname':arr[2]}; 
    } 
} 

Case3.cfm

<cfscript> 
    writedump(Case3::splitFullName("John Doe")) 
</cfscript> 

 Adobe

Get help faster and easier

New user?

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online