Creating Loops (CFLOOP)  
 
 

Looping is a very powerful programming technique that lets you repeatedly display a set of instructions or some output depending on a particular set of conditions. CFLOOP allows for four different types of loops:

  • Index loops (also called FOR loops)
  • Conditional loops (also called WHILE loops)
  • Looping over a query
  • Looping over a list
  • Looping over a COM collection

You use the attributes of the CFLOOP tag to choose which type of loop to use.

 
 
  Index loops  
 
 

An index loop repeats based on a range of numeric values. Use this type of loop when you know the number of times the loop should run.

 
 
  Example of an index loop  
 

The INDEX variable will be incremented on each iteration of the loop. The following example loops five times, displaying the index value of the loop each time:

<CFLOOP INDEX="LoopCount" FROM="1" TO="5">
The loop index is <CFOUTPUT>#LoopCount#</CFOUTPUT>.<BR>
</CFLOOP>

The results would look like this in a browser:

The loop index is 1.

The loop index is 2.

The loop index is 3.

The loop index is 4.

The loop index is 5.

 
 
  Example 2 of a stepped index loop  
 

The STEP value has a default value of 1, but you can set the step value to change the way the INDEX value is incremented. The following example counts backwards from 5:

<CFLOOP INDEX="LoopCount" FROM="5" TO="1" STEP="-1">
The loop index is <CFOUTPUT>#LoopCount#</CFOUTPUT>.<BR>
</CFLOOP>

The results would look like this in a browser:

The loop index is 5.

The loop index is 4.

The loop index is 3.

The loop index is 2.

The loop index is 1.

Index loops are commonly known as a FOR loop, as in `loop FOR this range of values.'

 
 
  Conditional loops  
 
 

A conditional loop iterates over a set of instructions while a given condition is true. To use this type of loop correctly, the instructions must change the condition every time the loop iterates until the condition evaluates as FALSE.

 
 
  Example  
 

The following example increments the parameter "CountVar" from 1 to 5.

<!--- Set the variable CountVar to 1  --->
<CFSET #CountVar#= 0>

<!--- Loop until CountVar is 5 --->
<CFLOOP CONDITION="CountVar LT 5">

<CFSET #CountVar#=#CountVar# + 1>
The loop index is <CFOUTPUT>#CountVar#</CFOUTPUT>.<BR>
</CFLOOP>

The results would look like this in a browser:

The loop index is 1.

The loop index is 2.

The loop index is 3.

The loop index is 4.

The loop index is 5.

Conditional loops are commonly known as WHILE loops , as in `loop WHILE this condition is true.'

 
 
  Query Loops  
 
 

A loop over a query repeats for every record in the query result set. The CFLOOP results are just like a CFOUTPUT. During each iteration of the loop, the columns of the current row will be available for output.

On the other hand, using a CFLOOP query is much slower than using CFOUTPUT with a query.

 
 
  Example: Using CFLOOP to display a record set  
 

The following example shows a CFLOOP tag that works just like a CFOUTPUT:

<CFQUERY NAME="MessageRecords" DATASOURCE="Customer">
    SELECT * FROM Messages
</CFQUERY>

<CFLOOP QUERY="MessageRecords">
    <CFOUTPUT> #Message_ID# </CFOUTPUT><BR>
</CFLOOP>
 
 
  Example: Next n record sets in a query  
 

CFLOOP also provides iteration over a record set with dynamic starting and stopping points. Thus, you can begin at the tenth row in a query and end at the twentieth.

Using this mechanism provides a simple means to get the next n sets of records from a query. The following example loops from the tenth through the twentieth record returned by "MyQuery:"

<CFSET Start=10>
<CFSET End=20>

<CFLOOP QUERY="MyQuery" STARTROW="#Start#" ENDROW="#End#">
    <CFOUTPUT>#MyQuery.MyColName#</CFOUTPUT><BR>
</CFLOOP>

The loop is done when there are no more records or when the current record is greater than the value of the ENDROW attribute .

 
 
  Example: Looping over a query  
 

The following example uses the CFINCLUDE tag to combine into a single document all the application pages returned in querying a list of application page names .

<CFQUERY NAME="GetFile" DATASOURCE="Library" MAXROWS=5>
    SELECT FileName FROM Templates
</CFQUERY>

<CFLOOP QUERY="FileName">
    <CFINCLUDE TEMPLATE="#FileName#">
</CFLOOP>

If you just need to loop through a query "Record Count" number of times, you can use CFOUTPUT, as in this example:

<CFOUTPUT QUERY="MyQuery">
    Text and #variablename#
</CFOUTPUT>
 
 
  List Loops  
 
 

Looping over a list offers the option of walking through elements contained within a variable or value returned from an expression. In a list loop, the INDEX attribute specifies the name of a variable to receive the next element of the list. The LIST attribute holds a list or a variable containing a list.

This loop displays the names of each of the Beatles:

<CFLOOP INDEX="ListElement" LIST="John,Paul,George,Ringo">
    <CFOUTPUT>#ListElement#</CFOUTPUT><BR>
</CFLOOP>

Although CFLOOP expects elements in the list to be separated by commas by default, you are free to specify your own element boundaries in the DELIMITER attribute . Here's the same loop as before, only this time CFLOOP will treat commas, colons, or slashes as list element delimiters:

<CFLOOP INDEX="ListElement" 
    LIST="John/Paul,George::Ringo" DELIMITERS=",:/">
    <CFOUTPUT>#ListElement#</CFOUTPUT><BR>
</CFLOOP>

Delimiters need not be specified in any particular order. Note that consecutive delimiters are treated as a single delimiter; thus, the two colons in the previous example are treated as a single delimiter between "George" and "Ringo."

 
 
  Looping over a COM collection  
 
 

The CFLOOP COLLECTION attribute allows you to loop over a COM/DCOM collection object. A COM/DCOM collection object is a set of similar items referenced as a group rather than individually. For example, the group of open documents in an application is a type of collection. Each collection item is referenced in the CFLOOP by the variable name you supply in the ITEM attribute. This type of iteration is generally used to access every object within a COM/DCOM collection. The loop is executed until all objects have been accessed.

The COLLECTION attribute is used with the ITEM attribute in a CFLOOP. In the example that follows, ITEM is assigned a variable called file2, so that with each cycle in the CFLOOP, each item in the collection is referenced. In the CFOUTPUT section, the name property of the file2 item is referenced for display.

This example employs a COM object to output a list of files. In this example, FFUNC is a collection of file2 objects.

<CFOBJECT CLASS="FileFunctions.files" 
    NAME="FFunc"
    ACTION="Create">

<CFSET FFunc.Path="c:\">
<CFSET FFunc.Mask="*.*">
<CFSET FFunc.attributes=16>
<CFSET x=FFunc.GetFileList()>

<CFLOOP COLLECTION=#FFUNC# ITEM="file2">
    <CFOUTPUT> #file2.name# <BR>
    </CFOUTPUT>
</CFLOOP>
 
 
  Nesting loops  
 
 

A CFLOOP block can also contain other CFLOOPs. In this case, the inner loop will execute from start to finish as many times as the outer loop executes. Loops can be nested as deeply as you like.

Here the inner loop will execute on each iteration of the outer loop for a grand total of 15 times:

<CFLOOP INDEX="OuterLoopCount" FROM="1" TO="3">
    <CFOUTPUT>Outer loop #OuterLoopCount#</CFOUTPUT><BR>

    <CFLOOP INDEX="InnerLoopCount" FROM="1" TO="5">
    <CFOUTPUT>Inner loop #InnerLoopCount#</CFOUTPUT><BR>
    </CFLOOP>
</CFLOOP>
 
 
  Breaking out of a loop  
 
 

When ColdFusion encounters the CFBREAK tag in a loop, it terminates the execution of the loop and proceeds to process the application page starting with the line immediately following the end of the loop. This is generally less elegant than constructing the loop with an appropriate conditional, but there are times when breaking out of a loop can simplify a tag structure that's complicated or deeply nested.

The following example isn't a terribly good use of CFBREAK, but it shows the tag in action:

<CFLOOP INDEX="LoopCount" FROM=1 TO=100>
The value is <CFOUTPUT>#LoopCount#</CFOUTPUT>.<BR>
    <CFIF LoopCount IS 7>
    <CFBREAK>
    </CFIF>
</CFLOOP>

The results would look like this in a browser:

The value is 1.

The value is 2.

The value is 3.

The value is 4.

The value is 5.

The value is 6.

The value is 7.

 
 
  For more information  
 

For more information on the CFML tags used for controlling page flow, see the CFML Language Reference.



 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.