last edited byusericonadmin on 29-Apr-2010

Contents

Component Basics

ColdFusion Components, or CFCs, are the starting point for building object oriented systems so it is important to understand what they are and how they differ from objects.

What is a component?

A component is simply a text file that describes a set of variables and functions which are used as a "blueprint" or "template" for creating objects. Once you have created a component then you can use the createObject() function to create objects based on your component.

Component file names

All components file names must end with ".cfc".

It is common practice that component filenames use upper camel case. The same naming convention is used when providing the component's name as a parameter to createObject().

Example file names:

Examples of creating these objects:

Component structure

Let's take a look at a simple component called ThresholdCounter.cfc so we can review its structure and take a look at some common best practices. No need to worry about what this component is doing at the moment, we will look at that later. For now let's focus on it's structure. 

<cfcomponent output="false">

    <!--- PRIVATE VARIABLES --->

    <cfset variables.threshold = 100>
    <cfset variables.currentTotal = 0>

    <!--- PUBLIC FUNCTIONS --->

    <cffunction name="addAmount" output="false">
        <cfargument name="amount" type="numeric" required="true">
        <cfset variables.currentTotal = variables.currentTotal + arguments.amount>
    </cffunction>

    <cffunction name="thresholdHasBeenReached" output="false" returntype="boolean">
        <cfset var thresholdReached = variables.currentTotal ge variables.threshold>
        <cfreturn thresholdReached>
    </cffunction>

</cfcomponent>

Suppress whitespace output

Notice that the <cfcomponent> tag and the <cffunction> tags both have output="false". Always put these on every component and function that you create. This prevents whitespace being unintentionally sent to the browser. As a general rule, your components should never send output directly to the browser.

Use the variables scope to keep your data private

Our two data values are places in the "variables" scope. 

<cfset variables.maxThreshold = 100>
<cfset variables.currentTotal = 0>

You should place all of your component variables in this scope. The variables scope is also called the "private" scope of the component. This means that you cannot access these variables directly from outside the object. For example, you can only change the currentTotal variable by calling the addAmount() function. There is no other way to change the currentTotal variable.

Correctly scope local function variables

Local function variables are variables that are only used within a single function. In the thresholdHasBeenReached() function we have a local function variable called thresholdReached. This has been "var"ed to ensure the variable is kept private to the function. If this is not done, then the variable will "leak out" into the variables scope which can cause later problems. 

<cfset var thresholdReached = variables.currentTotal ge variables.threshold>

In ColdFusion 8 and earlier you must "var" all local function variables at the top of your function.

In ColdFusion 9 you may var your variables anywhere in the function, or you may use the new "local" scope that exists in functions. For example: 

<!--- Using ColdFusion 9's "local" scope in a function. --->
<cfset local.thresholdReached = variables.currentTotal ge variables.threshold>

To ensure you have correctly "var"ed all of your component's local variables you can scan your code using the excellent VarScoper tool by Mike Schierberl.

Specify the scopes of all variables

When writing code always specify the scope that all of your variables are in. This can help prevent subtle bugs being introduced in your code.

For example, this is good: 

<cffunction name="addAmount" output="false">
    <cfargument name="amount" type="numeric" required="true">
    <cfset variables.currentTotal = variables.currentTotal + arguments.amount>
</cffunction>

And this is bad: 

<cffunction name="addAmount" output="false">
    <cfargument name="amount" type="numeric" required="true">
    <cfset currentTotal = currentTotal + amount>
</cffunction>

First variables, then functions

It is good practice to list out all of your variables at the top of your component and then follow them with your component's functions. In addition to this, you should always list out every variable you plan to use at the top of your components. This helps others reading the code to immediately see the set of shared variables within your component.

In this example, comments have been added to identify these sections. These comment dividers can help other team members quickly find sections within your components.

Specify the types of your data

It is good practice to specify the types of variables in your function arguments and your function return values. These will help catch problems with invalid data being passed into or out of your functions.

Other common practices

There are some other common practices that are not shown here that you can also use these if you prefer their style.

XHTMLise your tags

It has become common for some developers write ColdFusion tags follow correct XHTML syntax. For example, rather than writing this: 

<cffunction name="addAmount" output="false">
    <cfargument name="amount" type="numeric" required="true">
    <cfset variables.currentTotal = variables.currentTotal + arguments.amount>
</cffunction>

You would write this: 

<cffunction name="addAmount" output="false">
    <cfargument name="amount" type="numeric" required="true" />
    <cfset variables.currentTotal = variables.currentTotal + arguments.amount />
</cffunction>

Notice that the <cfargument> and <cfset> tags are "closed" with a "/>" at the end. ColdFusion will accept both styles and it is up to your team to decide which style you prefer.

It is worth noting, however, that if you use this syntax when calling a custom tag then it will cause the code to be executed twice. This behaviour is by design. Read more about why the code is executed twice or see the ColdFusion documentation. 

<!--- This executes once --->
<cfmodule template="displayUser.cfm">

<!--- This executes twice --->
<cfmodule template="displayUser.cfm" />

Use a hint attribute

A hint attribute can be useful to briefly describe the purpose of a function. For example 

<cffunction name="addAmount" output="false" hint="Adds the specified amount to the Threshold Counter.">
    <cfargument name="amount" type="numeric" required="true" />
    <cfset variables.currentTotal = variables.currentTotal + arguments.amount />
</cffunction>

Hints can also be useful if you plan to generate documentation for your components

Object oriented terminology

In CFML these building blocks for objects are called components.

In other object oriented languages these building blocks are more commonly referred to as classes.

From here

Take a look at a simple example of an object.

 

© 2009-2010 Kevan Stannard