Invoking CFCs

Contact Us or call 1-877-932-8228
Invoking CFCs

Invoking CFCs

CFC methods are invoked using the <cfinvoke> tag. The tag does one of the following:

  1. instantiates the specified component transiently and then invokes the specified method.
  2. invokes the specified method on a component that has already been instantiated (e.g, with the <cfobject> tag).

Passing Argument Values

CFC method arguments can be passed in any of the following ways:

  1. Using a nested <cfinvokeargument> tag with name and value attributes:
    <cfinvoke 
    	component = "component_name" 
    	method="method_name" 
    	returnvariable="return_variable">
    	<cfinvokeargument name="arg1" value="value">
    	<cfinvokeargument name="arg2" value="value">
    </cfinvoke>
  2. Using attribute-value pairs in the <cfinvoke> tag itself:
    <cfinvoke 
    	component = "component_name" 
    	method="method_name" 
    	returnvariable="return_variable" 
    	arg1="value"
    	arg2="value">
  3. Using the argumentCollection attribute with the value set to a structure storing name-value pairs:
    <cfset args = StructNew()>
    <cfset args.arg1 = "value">
    <cfset args.arg2 = "value">
    <cfinvoke 
       component="component_name" 
       method="method_name" 
       argumentCollection="#args#" 
       returnVariable="return_variable">

The following example shows different ways of invoking the ImageFlipper method of the Images CFC:

Code Sample:

CFCs/Demos/Images.cfm
<html>
<head>
<title>Invoking Component Methods</title>
</head>
<body>
<h1>Invoking Component Methods</h1>
<h2>Example 1: Transient Instantiation</h2>
<cfinvoke component = "Images" method="ImageFlipper" returnvariable="imgpath">
	<cfinvokeargument name="directory" value="Images/Runners">
</cfinvoke>
<cfoutput><img src="#imgpath#"/></cfoutput>

<h2>Example 2: Using attributes rather than cfinvokeargument</h2>
<cfinvoke 
	component = "Images" 
	method="ImageFlipper" 
	returnvariable="imgpath" 
	directory="Images/Runners">

<cfoutput><img src="#imgpath#"/></cfoutput>

<h2>Example 3: Passing the arguments using argumentCollection</h2>
<cfset args = StructNew()>
<cfset args.directory = "Images/Runners">
<cfset args.extensions = "jpg">
<cfinvoke 
   component="Images" 
   method="ImageFlipper" 
   argumentCollection="#args#" 
   returnVariable="imgpath">
<cfoutput><img src="#imgpath#"/></cfoutput>

<h2>Example 4: Separate instantiation and method invocation</h2>
<cfset args = StructNew()>
<cfset args.directory = "Images/Runners">
<cfset args.extensions = "jpg">
<cfobject 
   name="objImage" 
   component="Images2">

<cfloop index="i" from="1" to="7">

<cfinvoke 
   component="#objImage#" 
   method="ImageFlipper" 
   directory="Images/Runners" 
   extensions = "jpg"
   returnVariable="imgpath">

<cfoutput><img src="#imgpath#"/></cfoutput>
</cfloop>

</body>
</html>

Transient Instantiation

The first example above uses transient instantiation. As the component has not yet been instantiated, <cfinvoke> instantiates the component, calls the method and then destroys the component. This is useful when all you need to do is call one method on the object. The argument is passed using <cfinvokeargument>.

The second and third examples are essentially the same, except the second uses attribute-value pairs and the third uses the argumentCollection attribute to pass arguments to the method.

Separate Instantiation and Method Invocation

The fourth example instantiates the component with the <cfobject> tag and then, using a loop, calles the ImageFlipper method seven times. Because the object is being used more than once, it's better to instantiate it separately. It will be destroyed when the page exits.

THIS Scope

You may also notice that the component is built a little differently. Instead of using session variables, it holds a picture variable in the THIS scope that stores the number of the picture showing. The ImageFlipper method changes the value of THIS.picture each time it is called. Variables in the THIS scope are properties of the component instance. That is, if another instance of this component were created, it would have its own picture property.

Next