ColdFusion Components - An Introduction

A Simple CFC

Now that you have a general overview of the flow and lingo, let’s put this knowledge to work so you can really grasp the concept of CFCs.

The first thing we need to do is create a new file and save it with a .cfc extension. Call this file users.cfc; we’ll use it to store all our user methods. I also recommend you store all your CFCs in a central folder called components, cfc -- whatever name takes your fancy.

Now, open this file in your favorite text editor and type the following:

<cfcomponent displayname="Users CFC” hint="This is the CFC for my user stuff">  
 <!--- This function gets all the users and their  data from the DB --->  
 <cffunction name="get_all_users" hint="Gets all users in the database" returntype="query">  
   <cfquery name="get_em" datasource=#APPLICATION.db_source#>  
     select * from from users  
   </cfquery>  
   <cfreturn get_em>  
 </cffunction>  
</cfcomponent>

Save your file, so you don’t lose the work, and let’s go through the code line by line.

<cfcomponent displayname="user cfc" hint="This is the CFC for my user stuff">

This first line tells the CF server that this is a Coldfusion Component. The displayname is the name that displays when documentation is generated; the hint contains descriptive text about the CFC as a whole.

 <!--- This function gets all the users and their  data from the DB --->  
 <cffunction name="get_all_users" hint="Gets all users in the database" returntype="query" output=”false”>

Next we see a comment that describes what the CFC does. After the comment is a cffunction tag with the attribute’s name, hint, returntype, and output setting. name presents the name of the function being called. hint presents descriptive text about this function. returntype tells the CF server what kind of data is going to be returned by this function. And finally, output tells the server whether this function acts as if it’s in a <cfoutput> tag, or a <cfsilent> tag. Basically, we use the output setting to define whether we want the function to process cfoutput tags within the cffunction (output=”true”), or we want those tags to be suppressed (output=”false”).

You have a few choices for returntype, so be sure to pick the one that suits your function. These types are pretty self-explanatory:

• Any
• Array
• Binary
• Boolean
• Numeric
• Date
• Guid
• Query
• String
• Struct
• Uuid
• Variablename
• Void

On top of all this, we could also define access and role attributes to help control who has access to the function and its output. The roles attribute works in unison with the cflogin tag. We can define roles, etc., with the cflogin tag; those roles then dictate the specific methods a user can and cannot invoke. We could devote a whole article to this topic but, in short, roles are great for security when your application utilizes the built-in authentication of ColdFusion. If you’d like to know more about these topics, check out the ColdFusion documentation and Macromedia Website.

   <cfquery name="get_em" datasource=#APPLICATION.db_source#>  
     select * from from users  
   </cfquery>

This next snippet of code represents the actual query that we’ll run against the database. You’ll notice that I’ve used the variable #APPLICATION.db_source# instead of naming a specific datasource. This is a personal code preference, so feel free to either store this value in your application.cfml using the cfset tag, or specify the datasource name as it is set up in the CF Administrator.

   <cfreturn get_em>

Next we have to return the query to the page that called this function. As we want to return the entire query to the calling page, and because we set returntype="query", we insert the name of the query as it appears in the name attribute for the cfquery tag.

One thing to keep in mind for the cfreturn tag is that it will return only one value at a time. So if you want or need multiple values returned, you must put them in an array or structure, and then return that array or structure.

 </cffunction>  
</cfcomponent>

Finally, we close out the function and component tags.