User Guide

216 Chapter 10: Building and Using ColdFusion Components
When you store components in the same directory, they are members of a component package.
You can group related CFCs into packages. Your application can refer to any component in a
directory specifically by using a qualified component name that starts with a subdirectory of one
of the accessible directories and uses a period to delimit each directory in the path to the directory
that contains the component. For example, the following example is a qualified name of a
component named
price:
catalog.product.price
In this example, the price.cfc file must be in the catalog\product subdirectory of a directory that
ColdFusion searches for components, as listed in the preceding table. When you refer to a
component using the qualified name, ColdFusion looks for the component in the order described
in “Specifying the CFC location” on page 224.
Establishing a descriptive naming convention is a good practice, especially if you plan to install
the components as part of a packaged application.
Using ColdFusion components
There are two ways to use a CFC:
• 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.
• 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.
This section describes how to use CFCs, including the following topics:
• Tags for using CFCs
• CFC invocation techniques
• Instantiating CFCs