When I was a noob (new user) to coldfusion, I racked my brain, and spent countless hours trying to figure out when to use which.  So after speaking to many developers, and doing countless tests of my own, I will give you my take.  Hopefully you will find this information useful, and if you are a new user, maybe save you some time when writing your first application.

These will be rather simple examples, so if you have a more in-depth issue, please post your problem here and I will do my best to answer that for you.

First, we'll start off with CFLOOP, it's different types and it's most common attributes.

(Curtesy of Adobe Livedocs)

• cfloop: index loop
• cfloop: conditional loop
• cfloop: looping over a date or time range
• cfloop: looping over a query
• cfloop: looping over a list, a file, or an array
• cfloop: looping over a COM collection or structure

We are only going to cover index, lists, and query type loops here for time sake. And this is just a basic overview to give you an understanding of CFLOOP so that when I compare it to CFOUTPUT, you will see the difference a little easier.

First, we'll descuss an index list. 

It is the most basic loop, where you specify from: to: values and assign them to an index variable.  There is also an optional step attribute that allows you to specify what number to increment by.  i.e. if you have a loop from 0 to 120, and you set a step of 3, it would set the index value to 0,3,6,9… 120.

syntax
<cfloop index="parameter name" from="beginning value" to="ending value" [optional: step="increment"]>
HTML or CFML code …
</cfloop>

The best example for this would be if you knew how many times to loop or if you passed an integer to loop to for specific processing.  Maybe you want to loop 10 times to get 10 random numbers in a list.

<cfset randomList = ""> //empty list to append data to
<cfloop index="i" from="1" to="10">
<cfset randomList = listAppend(randomList,i)>
</cfloop>
<cfoutput>#randomList#</cfoutput> 

Next, a query loop is exactly what it says. 

It loops over the records in a query so you can display the data.

syntax
<cfloop query = "query name" [optional: startRow = "row number" endRow = "row number"]> //the startRow and endRow are used for things such as adding pagination to your output
HTML or CFML code …
</cfloop>

Example:

<cfquery name="qMyTable" datasource="#application.dsn#">
SELECT recordID,detail
FROM myTable
</cfquery>
<table>
<tr>
<td>Record</td>
<td>Detail</td>
<td>Delete</td>
</tr>
<cfoutput>
<cfloop query="qMyTable">
<tr>
<td>#qMyTable.recordID#</td>
<td>#qMyTable.detail#</td>
<td><input type="checkbox" name="Checkbox" value="#qMyTable.recordID#"></td>
</tr>
</cfloop>
<cfoutput>
</table> 

You still have to wrap your loop in CFOUTPUT tags, so that your variable will show.  I wrap the entire loop to use less code, but you could wrap each variable independantly if you wanted to, both will work.

Anyway… you should end up with an output that looks like this:

Finally, the list loop.

This loops over a list of any kind, and assigns each list element to the index variable (list example:  'coldfusion,8,is,awesome' )  //Does not have to all be the samedata type

syntax
<cfloop index="index name" list="list items" [optional: delimiters="item delimiter"]>
HTML or CFML code …
</cfloop>

The best example for this would be if you had many form fields, such as checkboxes, that you wanted to pass to an action page(old way) or model(new MVC way) to do a mass update or deleting of records.

If you take the table from the last loop I just discussed:

Now if you happen to check checkbox 2 & 3 to delete.  You will have a field variable called checkbox with a list of record id's. So we will loop over this form field to delete the checked records.  Here is the code to do so.  Note: if a checkbox is not checked, the field is not passed in the FORM scope thus leaving it blank.

<cfloop index="i" list="#FORM.Checkbox#">
<cfquery datasource="#application.dsn#">
DELETE FROM myTable
WHERE recordID = #i#
</cfquery>
</cfloop> 

Now, these loops are the most common, but you can loop on just about anything in CF, i.e. collections, files, arrays, dates, etc… but that's for another day and another blog post.

Now to explain CFOUTPUT with a query attribute.

syntax
<cfoutput query="query name" [optional: group="query column" groupCaseSensitive="yes|no" maxRows="maximum rows to display" startRow="start row"]>
HTML or CFML code …
</cfoutput>

This is very comparable to the second loop above, the loop with a query. The only difference being what you intend to get for an output.  You could duplicate the loop above and make it look like this instead

<cfquery name="qMyTable" datasource="#application.dsn#">
SELECT recordID,detail
FROM myTable
</cfquery>
<table>
<tr>
<td>Record</td>
<td>Detail</td>
<td>Delete</td>
</tr>
<cfoutput query="qMyTable">
<tr>
<td>#qMyTable.recordID#</td>
<td>#qMyTable.detail#</td>
<td><input type="checkbox" name="Checkbox" value="#qMyTable.recordID#"></td>
</tr>
<cfoutput>
</table>

This works too, but I tend to use CFLOOP for these sort of simple outputs.  I use CFOUTPUT when I need to group fields and still show their associated data.  I'll explain.

If we expand on the above query to make it include multiple phone numbers for each record like so:

<cfquery name="qMyTable" datasource="#application.dsn#">
SELECT a.recordID,a.detail,b.phone
FROM myTable a INNER JOIN phoneNums b ON a.recordID = b.recordID
</cfquery>

With 3 records in myTable, and 2 phone numbers each, we will have a total of six records and the query output will look like this:

Now… say we want to show three records with each phone number.  Looping over this query with CFLOOP would require nested CFLOOPS and sub-queries, which is not ideal. So we will use CFOUTPUT with a query attribute and a group attribute.  Here is the code:

<table>
<tr>
<td>Record</td>
<td>Detail</td>
<td>Delete</td>
</tr>
<cfoutput query="qMyTable" group="recordID">
<tr>
<td>#qMyTable.recordID#</td>
<td>#qMyTable.detail#</td>
<td><cfoutput>#qMyTable.phone#<br></cfoutput></td>
</tr>
<cfoutput>
</table>

The nested cfoutput will loop over the records for the current recordID to display the multiple phone numbers.  The table will look like this:

This is a time saver over the nesting of CFLOOP's. You can even nest your CFOUTPUT's further than this, grouping a second time and outputting multiple records for that specific group. This is advanced, but if you would like to see an example, let me know.

I hope this helps any noobs or anyone who is a seasoned user that never understood the difference.

My problems with CFFLUSH and ColdFusion 8 are baffling me. I am trying to display an animated .gif file while my page is loading, but for some reason it does not show. I have installed all the updates and hotfixes for coldfusion, but to no avail, it still does not work. So.. I am forced to use AJAX. Hopefully ColdFusion update 2 or another hotfix will remedy this issue, who knows, I may be missing something else all together.

I did find another blog posting over at orangepips that discusses a strikingly similar issue, not sure if this is completely related to my issue, but it is some good information;

Unfortunately, the solution on this blog doesn't work for me either, so I will give a quick example of what I did with AJAX to get around this.

2008/8/14: EDIT::: I just did some more research and found out what the real
problem is. Since I have moved to ColdFusion 8, I also moved to
Windows Server 2003, which has IIS 6, which I have http GZIP compression
enabled. Through some web searching I found that since IIS will
compress the whole data output and then send it to the client, it does
not provide enough data to CFFLUSH to say "Hey, flush this data until
the page loads". It simply shows a blank screen until the page
suddenly loads. If anyone knows away to get this to work with CFFLUSH, please
comment. But for now, my process below definitely works and just may be the way of the future.

I will be using my AJAX framework of choice, Prototype. Prototype is one of the most popular frameworks out there and is very easy to use and has a smaller learning curve compared to some of it's competitors. I highly recommend it. As a side note, I also use Scriptaculous, which works very well with prototype. Scriptaculous is for creating site animations, auto-complete searches, and drag and drop features.

Okay.. Lets get started. This is a very crude before and after, but it should get my point across.

Before.. (1 File) (eventually this will be merged into an MVC framework, but this is legacy code I am dealing with, so it's just a single file for now)

"Coldfusion code (queries, object creation, and any other things that take long)"
<!--- Show the loading image --->
<div ID="loaderIMG" align="center">
<strong>searching</strong> <img src="images/loader.gif" border="0" />
</div>
<CFFLUSH>
<!--- To hide the image --->
<SCRIPT>
document.all.loaderIMG.style.display='none';
</SCRIPT>
"Display the HTML results down here"

After.. (2 files)

Search.cfm

<html>
<head>
<SCRIPT src="/js/prototype/prototype.js"></SCRIPT>
<script>
function doSearch(){
var criteria = $F('criteria'); //Prototypes way of getting form field values
var category = $F('category');
$('results_container').innerHTML='<div align="center"><strong>searching</strong> <img src="images/loader.gif" border="0" /></div>';
var options = {parameters : {criteria:criteria, category:category}, method:'get', onComplete:showSearch, onFailure:reportError};
new Ajax.Updater($('results_container'),'SearchResults.cfm', options);
return false;
}
// For returning an error to the user if the ajax call fails
function reportError(request){
$('results_container').innerHTML='<b><font size="4" color="red">! Sorry. There was an error.<b></font>'
}
</script>
</head>
<body>
<div id="master_container">
<div id="search_form" style="width:600px;">
<fieldset>
<legend>Quick Search&nbsp;</legend>
<form name="search" method="get" style="display:inline;">
<input type="text" name="criteria" maxlength="50" size="20">
<select name="category">
<option value="U">Users</option>
<option value="C">Customers</option>
<option value="S">Suppliers</option>
</select>
<input type="button" name="search" value="search" onclick="doSearch();">
</form>
</fieldset>
</div>
<div id="results_master_container" style="width:600px;">
<fieldset style="height:473px;">
<legend>Search Results&nbsp;</legend><br />
<div id="results_container">Perform your search...</div>
</fieldset>
</div>
</div>
</body>
</html>

SearchResults.cfm

"Coldfusion code (queries, object creation, and any other things that take long)"
"Display the HTML results down here"

What happens here in the after section, is when you click "search" on AjaxCall.cfm, it calls the doSearch(); function. This function includes some things to process the request. First it includes the values from the form to use for the search by settings vars of "criteria" and "category". Next.. the code line of "$('results_container').innerHTML='<div align="center"><strong>searching</strong> <img src="images/loader.gif" border="0" /></div>';" updates my search results container with the loading image. This will display until the AJAX call is complete. The next line sets some parameters and options for the call. It's not necessary to make it it's own variable, you could put it right into the AJAX call, but I find that it looks cleaner this way and is easier to debug.

Now for where the magic happens. The line "new Ajax.Updater($('results_container'),'SearchResults.cfm', options);" calls on SearchResults.cfm to do the search and create the HTML output. Once processing is complete, it updates the results_container div with the HTML that was generated. I also threw in an example of how to return an error to the user if the ajax call fails. As you can see, it's not that difficult. This will also help with the merge to an MVC framework, now that this is basically the model and the controller. The view will just have to be separated out. But that is for another posting in the future.

If you want to make your own loading images, you can go to AjaxLoad.info. You can make many different types there and it's much easier than making your own.

For the longest time, I've pondered the question, which one is best to use when?  I will break these down a little and give you my preference. 

For you people who have been programming for a long time, and have used many different types of programming languages, you may already have a preference, so please chime in with any opinions.  These tags are basically just a tag form of common 'if' and 'switch' functions used in other languages such as Javascript, C#, etc…  There is also a function form of these that can be used within the <CFSCRIPT> tag, but for simplicity sake, I won't be discussing that.  Although if you are interested in this I can give you my thoughts.

<CFIF>
<CFIF> is your basic tag for if and else statements.  Now… these sort of statements are used everywhere, and they are used in a lot of different technical applications.  Mostly ones that involve math.  These can be used in common applications such as excel, but also are available in highly technical applications like Unigraphics CAD/CAM (3D modeling engineering and manufacturing application) Something I used in my old profession.

Lets begin by breaking down the code a little to get a better understanding of what these tags do.  Take the following statement:

<CFIF request.qLabels.Title NEQ "Coldfusion Freak">....content....</CFIF>

This is a string validation/conditional statement, there are other types which I will get into in a minute, but this is checking a 'title' value from a query called 'qLabels' in the request scope against a basic string text of 'Coldfusion Freak'.  The 'NEQ' is basically an acronym for NOT EQUAL, so whatever is indside this tag will only get displayed if 'request.qLabels.Title' is not equal to 'Coldfusion Freak'. Simple, basic, and effective to get the desired output. What about the other types I mentioned?

<CFIF request.qLabels.ID EQ 12345>....content....</CFIF>
<CFIF NOT request.qLabels.deleted>....content....</CFIF>

The first one here is a numeric check using the EQ(equal) operator, notice the lack of quotes denoting that it is infact a numeric value.  The second one here is a boolean check, to see if the boolean value is true.  If it's NOT true, then it will display the content. These are just a couple examples, and are the most common that I have come across. To learn more about <CFIF> visit the Adobe Livedocs. 

<CFSWITCH> & <CFCASE>
Now this is a more sophisticated tool for checking a variable for multiple outcomes.  I will break down the code again.

<CFSWITCH expression="#URL.pageToView#"> 
<CFCASE value="services"><cfinclude template="services.cfm"></CFCASE> 
<CFCASE value="products"><cfinclude template="products.cfm"></CFCASE> 
<CFCASE value="cart"><cfinclude template="cart.cfm"></CFCASE> 
<CFDEFAULTCASE><cfinclude template="home.cfm"></CFDEFAULTCASE>
</CFSWITCH> 

This is a basic navigation case where it checks the URL variable 'pageToView' to know what page to include for output.  As you can tell, this will be useful for any circumstance that has one variable the could have many different values.  A whole framework could be written around this and it would be very easy to debug and follow.

Now lets compare them with usage that will give you the same outcome (i'll use the same example I just used):

<CFSWITCH expression="#URL.pageToView#"> 
<CFCASE value="services"><cfinclude template="services.cfm"></CFCASE> 
<CFCASE value="products"><cfinclude template="products.cfm"></CFCASE> 
<CFCASE value="cart"><cfinclude template="cart.cfm"></CFCASE> 
<CFDEFAULTCASE><cfinclude template="home.cfm"></CFDEFAULTCASE>
</CFSWITCH>




<CFIF URL.pageToView EQ "services"> 
<cfinclude template="services.cfm">
<CFELSEIF URL.pageToView EQ "products"> 
<cfinclude template="products.cfm">
<CFELSEIF URL.pageToView EQ "cart"> 
<cfinclude template="cart.cfm">
<CFELSE> 
<cfinclude template="home.cfm">
</CFIF> 

These will both have the same outcome, so why choose one over the other? It really boils down to a preference.  In this example, it is rather simple, so the performance is not really an issue, but while coding, the <CFSWITCH> is cleaner and much easier to follow.  I have heard that if the <CFIF> statements become lengthy and complex, and <CFSWITCH> could be used, that it would be wiser to do so.  I have heard that <CFIF> uses more memory and thus can cause a problem if there are a huge number of users.  Through my trials and testing, I have not seen performance changes in either direction.  I have tried to make sure that my <CFIF> statements are concatenated as much as possible.  Look at the following code:

<CFIF NOT request.qLabels.deleted>
..and..
<CFIF NOT request.qLabels.deleted EQ 1>

I have also heard from many that it is wiser to remove the 'EQ 1' whenever possible. Now if you are checking for an explicit value of '1', then this is fine. But this is specialized for boolean values. If you just want to know if the boolean is true or not, just leave out the 'EQ 1' and the server is more responsive. I tested this using a loop of over 10000 records, checking if it's deleted or not using both these forms, and when the 'EQ 1' was not there, there a much smaller server load and the response time was faster by about 15%. This is not a huge amount, but it was a performance gain, so I recommend removing operators if possible. Just remember, this can only be done with boolean type values. Another example would be to check if there are any records to display output, and this go as follows:

<CFIF request.qLabels.recordcount>
show desired output of records
<CFELSE>
show message explaining that there is no records in the query
</cfif>
Instead of... 
<CFIF request.qLabels.recordcount GT 0>
show desired output of records
<CFELSE>
show message explaining that there is no records in the query
</cfif>

These may seem like small things, but with large numbers of users and lots of server calls, there can be huge performance gains, but before I get too far off track, lets get to the verdict of our original topic here.

Verdict
So <CFSWITCH> is a better choice for areas that have one variable with many different value choices.  And, <CFIF> is better for all areas where a simple or complex function check on a variable is needed.

I tend to use <CFSWITCH> where I can, and since I like to design my apps in an MVC (model, view, controller) setup, it makes for easier debugging and inclusion of data.