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")>ListLenwill return the value 5 to the variablelistLength. That's pretty simple, but here's a challenge for you: what is the value oflistLengthafter 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.ListLentakes 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
wordsvariable 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
containsoperator in an if statement, it would have returned true:<cfif "12,15,186,99,0" contains "18">
this is true.
</cfif>ListContainswill also take an optional third parameter that specifies the delimiter to use. Next, we'll look at theListFirstandListLastfunctions. They pretty much do exactly as you would expect.ListFirstreturns the first element of the list andListLastreturns 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
ListFindfunction 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,
ListDeleteAtwill 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
productIDover 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!
