By: David Medlock

January 25th, 2004

Reader Rating: 8

In the past two articles, we've discussed some of the more complex data structures in ColdFusion. While arrays and structs are extremely useful for very specific tasks, you'll probably find yourself using lists more often. Fortunately, lists are extremely easy to manage in ColdFusion.

For all you Java, C++, and Visual Basic developers, I'm going to let you know now that you'll be extremely jealous of ColdFusion after reading this article. ColdFusion makes it very easy to manipulate lists with its built-in functions. And with a little creativity, a good ColdFusion developer can surely find several million ways to make use of a list.

What is a List?

First, let's define what a list is in ColdFusion terms. A list is simply a string. The only difference between a string and a list is that a list is delimited by a specific character or set of characters. You can use any string as a list, and any list can be manipulated just like any string. For example, a,b,c,d,e,f,g is a comma delimited list. Or you could use a/b/c/d/e/f/g -- a forward-slash delimited list. The default delimiter for a ColdFusion list is the comma. Also, be aware that a/b/c is not the same as a / b / c. ColdFusion does not trim the white space from list elements. If a list includes spaces, you may want to use the Trim function on the elements.

Lists in Action

So, now that we know what ColdFusion defines as a list, we'll begin using lists. First of all, let's try getting the length of a list.

<cfset listLength = ListLen("a,b,c,d,e")>

ListLen will return the value 5 to the variable listLength. That's pretty simple, but here's a challenge for you: what is the value of listLength after the following code is executed?

<cfset listLength = ListLen("a,b,,c,,d,e")>

If you guessed 5, you're right. The reason is that ColdFusion ignores empty list elements. Now, let's say that we want to display every element in the list. This is extremely easy:

<cfloop list="a,b,c,d,e" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

This code displays each list element on a separate line. Now, if you have a list stored in a variable, don't forget to put pound signs (#) around the variable name when you pass it to the list attribute of the loop. Otherwise, it will not work correctly.

<cfset list = "a,b,c,d">
<!--- this works fine --->
<cfloop list="#list#" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

<!--- this outputs "list" --->
<cfloop list="list" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

Just be sure to wrap the variable name in pound signs when you loop over a list.

List Functions

There are also a few list functions that we must cover very briefly before we move on to bigger and better things. We've talked about ListLen, which returns the length of the list. ListLen takes one required parameter, which is the list you want to check the length of, and one optional parameter that specifies the delimiters you want to use. So, you can find out how many words are in a sentence by doing this:

<cfset words = ListLen("The quick brown fox jumps over the lazy dog.", " ")>

Notice that the second parameter specifies that the string passed in the first parameter is a space delimited list. After execution, the words variable contains the value 9.

Another useful function is ListContains. This will search the list for a substring and return a Boolean value that indicates whether the substring was found as a list element.

<cfset found = ListContains("12,15,186,99,0", "18")>

Notice that this returns false because the substring "18" is not an element in the list we passed as the first parameter. Notice that we do have 186 in the list, but because there is no element that is an exact match. If you were to use the contains operator in an if statement, it would have returned true:

<cfif "12,15,186,99,0" contains "18">  
   this is true.  
</cfif>

ListContains will also take an optional third parameter that specifies the delimiter to use.

Next, we'll look at the ListFirst and ListLast functions. They pretty much do exactly as you would expect. ListFirst returns the first element of the list and ListLast returns the last element.

<cfoutput>  
   <!--- displays "The" --->  
#ListFirst("The quick brown fox jumps over the lazy dog.", " ")#  
 
<!--- displays "dog." --->  
#ListLast("The quick brown fox jumps over the lazy dog.", " ")#  
</cfoutput>

The ListFind function lets us search for an element in a list. It returns the first index of the element (as an integer). Keep in mind that this search is case sensitive.

<cfset first = ListFind("1,2,3,1,5,6", "5")>

The value of first will be 5 when we execute this line of code.

Finally, ListDeleteAt will let us remove an element from the list. We simply pass the list to it and the position we want to delete.

<cfset newList = ListDeleteAt("1,2,3,4,5", 2)>

When we execute this code, the newList variable contains the value "1,3,4,5" because we've deleted the second element of the list, 2.

Using Lists with HTML Forms

I've found that the most common use for lists in ColdFusion is in combination with HTML forms. When you create a form that contains multiple elements of the same name -- checkboxes, for example -- the results are submitted as a list. Here's an example:

products.cfm:  
<form name="deleteProducts" action="delete.cfm">  
 Product 1: <input type="checkbox" name="productID" value="1"><br>  
 Product 2: <input type="checkbox" name="productID" value="2"><br>  
 Product 3: <input type="checkbox" name="productID" value="3"><br>  
Product 4: <input type="checkbox" name="productID" value="4"><br>  
<input type="Submit" value="Delete">  
</form>

Now, if you check the first three checkboxes and click "Delete", it's going to send the form variable productID over to the delete.cfm page as a list with the value "1,2,3". When we get to the delete page, we'll simply loop over the list:

delete.cfm:  
<cfif isDefined("form.productID")>  
 <cfloop list="#form.productID#" index="i">  
   <cfquery name="delete" datasource="myDSN">  
     DELETE FROM Products  
     WHERE ProductID = #i#  
   </cfquery>  
 </cfloop>  
</cfif>

Here, we check to see if the form variable is there. This is necessary when submitting checkboxes. If you don't check any of the checkboxes, the variable productID is not submitted. Therefore, when it reaches delete.cfm, it will not exist and an error will be thrown when you try to loop over the variable. We loop over the list of product IDs and execute a delete query on each one of them.

As you come across situations in your day to day coding, you'll find that you have many opportunities to apply this technique. Whether you're deleting products from a database or working with other HTML forms, you'll find that lists are very, very handy. This is one tool that you'll do well to familiarize yourself with.

In our final look at ColdFusion data structures, we'll examine ColdFusion queries. These are very useful and very easy to use and apply. Until next time, happy coding!