Accessing your CFC

Once you are ready to use your CFCs, you need to access the methods placed within. There are two ways to access a CFC:

• object instantiation

• invoking the CFC

Instantiating the object

When you instantiate a CFC, you create an instance of the component. This instance preserves the data within the CFC for as long as it exists. You would typically create an instance of a component at the top of the page. By doing so, you would have access to its methods and functions on the entire page, without having to create a new instance for each call.

There are three methods available to you to create an instance of the CFC:

• createObject

• cfobject

• using the NEW operator in ColdFusion 9

Using the createObject function

As used in our earlier examples, the createObject() function creates and returns a ColdFusion object.

<cfscript>
objGreeting = createObject('component', 'greetings');
</cfscript>

Listing 1.19

Here, we are creating a new instance of the "greetings" component. The first parameter tells the createObject() function that we want a component, and the second references the name of the component of which we want to create an instance.

While the CFC is in the same directory as the calling page, in the previous example, if we had the CFC within a different directory in the webroot, for example, a folder named components; this second parameter would read as follows:

createObject('component', 'components.greetings');

This is because the second parameter is a dot notation representation of the path to the component.

Using the cfobject tag

Similar to the createObject() function, the cfobject tag has three attributes.

<cfobject name="greetingsObject" component="greetings" type="component" />

Listing 1.20

The name attribute defines the name of the returned variable of the CFC instance so you can access the component to use your methods. The component attribute represents a dot notation path to the CFC you wish to instantiate. The third attribute, type, is optional, and has the default value component.

Using the NEW operator

The enhancements in ColdFusion 9 now provide an alternative way of creating an instance of a component object without using the createObject() function.

We can now create the object through the use of the new operator, like so:

<cfscript>
// create the object
objGreeting = new greeting();
</cfscript>

Listing 1.21

Using cfinvoke

You can invoke your component and access the method simultaneously by using the cfinvoke tag. When you invoke (call) the CFC using this tag, you are not creating an instance of the component that will be preserved and available for use elsewhere within your CFML page. Instead, you are creating an instance of the CFC that comes into existence as soon as you invoke the method, and ceases to exist as soon as the requested method has returned a result.

In essence, you are bringing the component to life long enough to get the details you need from it and closing it down as soon as the information is returned.

The cfinvoke tag

Let's make a call to our sayHello() method within the greetings.cfc component.

Add the following code to your hello.cfm template page:

<cfinvoke component="greetings" method="sayHello" returnVariable="strHello" />
<cfoutput>#strHello#</cfoutput>

Listing 1.22

Here, we are invoking the greetings component, selecting the method within the CFC that we want to access, (in this case the sayHello() function) and assigning a variable (strHello), to which the returned data will be saved for us to access it within the page.

Outputting the returnVariable onto the page will provide us with the same result as we have seen before.

Using cfinvokeargument

The cfinvoke tag also allows us to pass in parameters to the methods we are calling, by means of the cfinvokeargument tag.

<cfinvoke component="greetings" method="personalGreeting" returnVariable="strPersonalGreeting">
<cfinvokeargument name="firstName" value="Matt" />
<cfinvokeargument name="lastName" value="James" />
</cfinvoke>

Listing 1.23

We are sending our parameters used in the personalGreeting() method in a similar format to the cfargument tag, using the cfinvokeargument tag, which is nested within the cfinvoke tag. The cfinvokeargument tag takes the name and value of the argument and sends it into the method you are calling.

Using attributes as arguments

Alternatively, when using the cfinvoke tag, you can send through the parameters as named attribute-value pairs, providing one attribute per argument.

<cfinvoke component="greetings" method="personalGreeting" firstName="Gary" lastName="Brown" returnVariable="strPersonalGreeting" />

Listing 1.24

You can see in the previous code that the firstName and lastName parameters are written as attributes within the cfinvoke tag itself.

Using an argument collection

The optional argumentCollection attribute for the cfinvoke tag accepts a structure in the form of an associative array of arguments to pass into the method.

<cfscript>
// create a structure to hold the values
stuArguments = structNew();
stuArguments.firstName = "James";
stuArguments.lastName = "Brown";
</cfscript>
<cfinvoke component="greetings" method="personalGreeting" argumentCollection="#stuArguments#" returnVariable="strPersonalGreeting" />

Listing 1.25

The structure names must match the names of the arguments within the method.