Invoking CFC methods with the cfinvoke tag

The cfinvoke tag can invoke methods on a CFC instance or invoke CFC methods transiently. You can also use the cfinvoke tag to invoke CFC methods from within a CFC.

Invoking methods of a CFC instance

To invoke a component method of a CFC instance, use the cfinvoke tag and specify the following:

  • The CFC instance name, enclosed in number signs (#), in the component attribute.

  • The method name, in the method attribute.

  • Any parameters. For information on passing parameters, see Passing parameters to methods by using the cfinvoke tag.

  • If the component method returns a result, the name of the variable for the result in the returnVariable attribute.

The following procedure creates an application that displays the current UTC and local time.

  1. Create a file named tellTime2.cfc with the following code:

    <cfcomponent> 
        <cffunction name="getLocalTime" access="remote"> 
            <cfreturn TimeFormat(now())> 
        </cffunction> 
        <cffunction name="getUTCTime" access="remote"> 
            <cfscript> 
                serverTime=now(); 
                utcTime=GetTimeZoneInfo(); 
                utcStruct=structNew(); 
                utcStruct.Hour=DatePart("h", serverTime); 
                utcStruct.Minute=DatePart("n", serverTime); 
                utcStruct.Hour=utcStruct.Hour + utcTime.utcHourOffSet; 
                utcStruct.Minute=utcStruct.Minute + utcTime.utcMinuteOffSet; 
                if (utcStruct.Minute LT 10) utcStruct.Minute = "0" & utcStruct.Minute; 
            </cfscript> 
            <cfreturn utcStruct.Hour & ":" & utcStruct.Minute> 
        </cffunction> 
    </cfcomponent>

    The example defines two component methods: getLocalTime and getUTCTime.

  2. Create a ColdFusion page, with the following code and save it in the same directory as the tellTime component:

    <!--- Create the component instance. ---> 
    <cfobject component="tellTime2" name="tellTimeObj"> 
    <!--- Invoke the methods. ---> 
    <cfinvoke component="#tellTimeObj#" method="getLocalTime" returnvariable="localTime"> 
    <cfinvoke component="#tellTimeObj#" method="getUTCTime" returnvariable="UTCTime"> 
    <!--- Display the results. ---> 
    <h3>Time Display Page</h3> 
    <cfoutput> 
        Server's Local Time: #localTime#<br> 
        Calculated UTC Time: #UTCTime# 
    </cfoutput>

This example uses the cfobject tag to create an instance of the tellTime component and the cfinvoke tag to invoke the instance’s getLocalTime and getUTCTime methods. In this example, the CFC contains the functional logic in the methods, which return a result to the calling page, and the calling page displays the results. This structure separates the logic from the display functions, which usually results in more reusable code.

Invoking component methods transiently

In ColdFusion pages or components, the cfinvoke tag can invoke component methods without creating a persistent CFC instance.

To invoke a component method transiently, use the cfinvoke tag and specify the following:

  • The name or path of the component, in the component attribute.

  • The method name, in the method attribute.

  • Any parameters. For information on passing parameters, see Passing parameters to methods by using the cfinvoke tag.

  • If the component method returns a result, the name of the variable that contains the result, in the returnVariable attribute.

The following procedure creates an application that displays the local time.

  1. Create the following component and save it as tellTime.cfc:

    <cfcomponent> 
        <cffunction name="getLocalTime"> 
            <cfoutput>#TimeFormat(now())#</cfoutput>     
        </cffunction> 
    </cfcomponent>

    The example defines a component with one method, getLocalTime, that displays the current time.

  2. Create a ColdFusion page, with the following code, and save it in the same directory as the tellTime component:

    <h3>Time Display Page</h3> 
    <b>Server's Local Time:</b> 
    <cfinvoke component="tellTime" method="getLocalTime">

    Using the cfinvoke tag, the example invokes the getLocalTime component method without creating a persistent CFC instance.

Using the cfinvoke tag within the CFC definition

You can use the cfinvoke tag to invoke a component method within the component definition; for example, to call a utility method that provides a service to other methods in the component. To use the cfinvoke tag in this instance, do not create an instance or specify the component name in the cfinvoke tag, as the following example shows:

<cfcomponent> 
    <cffunction name="servicemethod" access="public"> 
        <cfoutput>At your service...<br></cfoutput> 
    </cffunction> 
    <cffunction name="mymethod" access="public"> 
        <cfoutput>We're in mymethod.<br></cfoutput> 
        <!--- Invoke a method in this CFC. ---> 
        <cfinvoke method="servicemethod"> 
    </cffunction> 
</cfcomponent>
Note: When you invoke a method from within the component definition in which you define the method, do not use the This scope, because this resets the access privileges.

Invoking methods by using dynamic method names

The cfinvoke tag is the only way to efficiently invoke different component methods based on variable data (for example, form input). In this case, you use a variable name, such as Form.method, as the value of the method attribute. In the following example, the user selects a report from a form:

<select name="whichreport"> 
    <option value="all">Complete Report</option> 
    <option value="salary">Salary Information</option> 
</select>

The cfinvoke tag then invokes the appropriate method, based on what the user selected:

<cfinvoke component="getdata" method="#form.whichreport#" returnvariable="queryall">