Calling CFCs

CFCs can be called in several ways, including <cfinvoke>, <cfobject> with function syntax, directly from a URL or form, and by Web service invocation (discussed in Chapter 24).

<cfinvoke>

The simplest form of calling a function in a component is the <cfinvoke> tag. This syntax requires that you call a function in a component with its full URL, like this:

 <cfinvoke component="Actors" method="getAllActors" returnvariable="qActors"> 

Required attributes are the component name and the method name, as well as a return variable name in which the CFC can place any returned value.

If the component is in the local directory, the component name can be just the name of the file containing the component, without the .cfc. If the component is in a path on your Web server, the component name should be the path to the Web server, with the slashes replaced by periods. (This is a standard used in other languages, including Java.) For example, if the component can be called on the local machine by using /com/objects/OWS/Actors.cfc, you'd specify the component as "com.objects.OWS.Actors".

You can specify parameters passed to <cfinvoke> in three ways. The first is to simply make them arguments that are part of the cfinvoke. Calling the getActorDetail function in this way looks like this:

[View full width]
 <cfinvoke component="Actors" method="getActorDetail" returnvariable="getActorDetailRet"  actor> 

Another way to pass arguments is to create a structure in which the keys are the names of the arguments. For example, you could do the following:

[View full width]
 <cfset args = structNew()> <cfset args.actorID = 3> <cfinvoke component="Actors" method="getActorDetail" returnvariable="getActorDetailRet"  argumentCollection="#args#"> 

The attribute argumentcollection allows you to pass in all your arguments in a single structure. This can be very useful when there are large numbers of arguments, when the same arguments are being passed around among methods of a component (argumentcollection="#arguments#"), or when you wish to pass all your form fields to a component that processes the form (argumentcollection="#form#").

<cfinvokeargument>

The second way to pass in the argument is using <cfinvokeargument>. This takes two parameters, name and value. When using <cfinvokeargument>, you must provide a closing </cfinvoke> to contain them. That previous call to getActorDetail looks like this when using <cfinvokeargument>:

 <cfinvoke component="Actors" method="getActorDetail"  returnvariable="qActorDetail"> <cfinvokeargument name="actorID" value="3"> </cfinvoke> 

<cfinvokeargument> gives you more options when running your code, and lets you optionally include an argument depending on logic. For example, suppose that in a detail page you want your code to only pass in the actor id argument if an ID is passed in from a form. That code could look like this:

 <cfparam name="form.actorID" default=""> <cfinvoke component="Actors" method="getActorDetail" returnvariable="qActorDetail">   <cfif form.actorID NEQ "">     <cfinvokeargument name="actorID" value="#form.actorID#">   </cfif> </cfinvoke> 

NOTE

A third argument for cfinvokeargument is omit. This is used to pass null values when calling Web services and will be covered in Chapter 24, "Creating and Consuming Web Services.".

<cfobject>

The second way to call your functions looks more like a traditional function call. Let's say we'd like to call getActorDetail with syntax like getActorDetail(1) to get the actor's information for the actor with actorID equal to 1. But how would ColdFusion know where to find the function? The way we do this is by creating an object that contains the component. To create a name for an object that we can use in a template, we use the <cfobject> tag. To create an object that holds the Actors component, we'd use this:

 <cfobject name="cfcActors" component="Actors"> 

The NAME is the handle by which we'll call the component, and the component name is specified in COMPONENT. We can then call the component using function syntax, as shown here:

 <cfobject name="cfcActors" component="Actors"> <cfoutput> The actor's name is #cfcActors.getActorDetail(1).NameFirstReal#. </cfoutput> 

We'll use <cfobject> more when we discuss CFCs that have their own data.

There's also a function, createObject(), that performs the exact same function as cfobject. The syntax to create the Actors component with createobject() looks like this:

 <cfset cfcActors = CreateObject("component", "Actors")> 

where the first parameter tells ColdFusion that we are creating a component, and the second parameter is the component. It returns the component itself.

note:

On Unix and Linux systems, component names and paths are case-sensitive.

Accessing a CFC Using a URL

Another way to access a CFC is to call a method directly from a URL. If your CFC is available to the world via a Web browser, entering the exact URL of the CFC forwards you to the introspection page for that CFC, covered in the next section, "Introspection"). However, if you pass the method name on the URL with method= and any other arguments as URL parameters, it'll run the URL for you.

We could create a new method in our component called dumpActorDetail that simply calls the getActorDetail method and dumps out the data. Listing 19.2 is the code to do that.

Listing 19.2. dumpActorDetail.cfcCalling a CFC from a URL

 <!---   dumpActorDetail added by Ken Fricklas 2/15/2005   Listing 19.2: Demonstrates remote access, calling CFC directly from URL. ---> <cffunction access="remote" name="dumpActorDetail" output="true" returntype="void"   displayname="Dump Actor Information" hint="Output actor information.">   <cfargument name="actorID" type="numeric" displayname="Actor ID"     hint="The ID of the Actor to get.  If missing, all actors are returned."     required="yes">   <!--- Call the getActorDetail method and dump the output --->   <cfset qActor = getActorDetail(actorID)>   <cfdump label="Actor number #actorID#" var="#qActor#">   <cfreturn> </cffunction> 

Then we could call this method with the URL:

http://localhost:8500/ows/19/Actors.cfc?method=dumpActorDetail&actorID=1

which will run the method directly from the URL and dump the result to the screen.

TIP

This can actually be a useful debugging technique, when you want a way to embed test code directly in a component.

Note that the ACCESS attribute of <cffunction> needs to be "remote" (the same as for a Web service) in order to invoke the method from a URL. You'll read more about the ACCESS attribute when we discuss security later in this chapter.