Adobe ColdFusion 8

Using ColdFusion components

There are two ways to use a CFC:

  1. You can instantiate a CFC object, which creates a CFC instance. You then invoke the methods of the instance. You can access the CFC methods and data as instance elements. You can also use the instance in the cfinvoke tag to invoke the CFC methods. When you instantiate a CFC, data in the CFC is preserved as long as the CFC instance exists, and ColdFusion does not incur the overhead of creating the instance each time you call a method.

    Instantiate CFCs to preserve data in the CFC. To ensure processing efficiency if you use the CFC more than once on a page, instantiate the CFC before you invoke its methods.

    Methods that are executed remotely through Flash Remoting and web services always create a new instance of the CFC before executing the method.

  2. You can invoke (call) a method of the CFC without creating an instance of the CFC, which is referred to as transiently invoking a method. In this case, ColdFusion creates an instance of the CFC that exists only from the time you invoke the method until the method returns a result. No data is preserved between invocations and there is no instance of the CFC that you can reuse elsewhere in your CFML. It is considered a best practice to create an instance of a CFC before invoking any of its methods, unless your CFML request uses the CFC only once. If you transiently invoke a method frequently, consider creating a user-defined function to replace the CFC method.

You can create persistent CFCs by assigning the CFC instance to a persistent scope, such as the Session or Application scope. This way, you can create CFCs for objects, such as shopping carts or logged-in users, that must persist for sessions. You can also create CFCs that provide application-specific data and methods.

Tags for using CFCs

The following table lists the tags that you use to instantiate or invoke a CFC. You use these tags on the CFML page on which you instantiate or invoke the CFC.

Tag

Description

cfinvoke

Invokes a method of a CFC.

cfinvokeargument

Passes the name and value of a parameter to a component method.

cfobject

Creates a CFC instance.

CreateObject

Creates a CFC instance.

CFC invocation techniques

ColdFusion provides many ways to instantiate CFCs and invoke CFC methods. The following table lists the techniques, including the ColdFusion tags and functions that you use:

Invocation

Description

For more information

cfinvoke tag

Invokes a component method. Can invoke methods of a CFC instance or invoke the methods transiently.

See Invoking CFC methods with the cfinvoke tag.

cfset tag and assignment statements

Invoke methods and access properties of a component instance.

See Using components directly in CFScript and CFML.

URL (HTTP GET)

Transiently invokes a component method by specifying the component and method names in the URL string.

See Invoking component methods by using a URL.

Form control(HTTP POST)

Transiently invokes a component method using the HTML form and input tags and their attributes.

See Invoking component methods by using a form.

Flash Remoting

ActionScript can transiently invoke component methods.

See Using the Flash Remoting Service.

Web services

The cfinvoke tag and CFScript consume web services in ColdFusion. External applications can also consume CFC methods as web services.

See Using Web Services.

Instantiating CFCs

If you use a CFC multiple times in a ColdFusion request, or if you use a CFC with persistent properties, use the cfobject tag or CreateObject function to instantiate the CFC before you call its methods.

The following example uses the cfobject tag to create an instance of the tellTime CFC.

<cfobject component="tellTime" name="tellTimeObj">

The following example uses the CreateObject function to instantiate the same component in CFScript:

tellTimeObj = CreateObject("component", "tellTime");

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.