Introduction to Data Structures in ColdFusion Part III - Lists

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!