This column will focus on some of the ways developers have of extending the core capacities of ColdFusion. Specifically, we will cover user-defined functions (UDFs), custom tags, and ColdFusion components (CFCs). Every other month I'll select one or two resources that are freely available to anyone and explain what makes it (or them) interesting - or just plain cool. If you'd like to suggest a particular resource, please e-mail me at ray@camden family.com.

I'll begin this month with a pair of UDFs developed by Nathan Dintenfas (http://nathan.dintenfass.com). The UDFs are named QueryString ChangeVar (www.cflib.org/udf.cfm?id=471) and QueryStringDeleteVar (www.cflib.org/udf.cfm?ID=472). You can probably guess by their names what they accomplish. Both UDFs work on the query string. Not sure what that is? The query string is everything you see in the URL after the location of the file. In the following URL:

http://www.cflib.org/udf.cfm?ID=472

the file name is udf.cfm. Everything after the question mark (?) is the query string. Most likely you've worked with the query string in the past and not realized it. Whenever you run a ColdFusion file that has a query string passed to it, the ColdFusion server automatically converts the query string into URL variables. Using the example above, the URL variable "ID" would be created with a value of 472.

There are times, however, when you want to use the current query string, and modify it. Let's consider a few examples. If you've ever written a self-posting form, then you probably had code that looked like this:

<form action="edit.cfm" method="post">

In this case the form will post back to itself - a file called edit.cfm. What happens if you come back later and decide that "edit.cfm" isn't a very descriptive name? If you change the filename to edit Article.cfm, you have to remember to update the form tag as well. One way around this is to simply make the action value of the form tag point to the current page dynamically:

<form action="#cgi.script_name#" method="post">

This code will work even after you rename the file. Taking things a bit further, your form may have used certain URL variables. For example, an edit form may have used url.id to determine which record in the database to load. Your form tag would need to pass that as well. As before, you could hard-code it, but it's just as easy to use the query string cgi variable:

<form action="#cgi.script_name#?#cgi.query_string#" method="post'>

What's nice about this method is that it will work with any filename, and will automatically pass back any URL variables that were sent to the file originally. This method works greatŠup to the point where your query string contains a large set of values - one of which you need to remove. Consider the following query string:

sort=title&sortDir=down&filter=bugs&start=21

This query string contains four name/value pairs. Three of them are used by an application to retrieve and sort data. The fourth item, "start", is used to determine what record to begin displaying. As you can imagine, this query string is typical of "next-n" type data interfaces. Where things get tricky is when you want to grab the query string, but without the start value. This is because you'll need to set a new start value. You could rebuild the query string from scratch. If you know that the string should contain url.sort, url.sortDir, and url.filter, this isn't a big deal. However, if the URL parameters change in the future, this is one more place where if code isn't updated, the application will break.

By using either of the two UDFs, Query StringChangeVar or QueryStringDeleteVar, we can easily modify the query string. Here's an example:

<cfoutput>
<a href="#cgi.script_name#?#queryString
ChangeVar("start",newstart)#">Next 20
Results</a>
</cfoutput>

This example uses the QueryStringChangeVar UDF to change the value of url.start to newstart (a value defined earlier.) The UDF returns the entire modified query string, so we simply add it after the question mark.

How does the UDF work? It's really not that complex. Listing 1 contains the code for the UDF. We'll focus on the important aspects of the function, after the initial var statements. The query string (which can either default to cgi.query_ string or use a string passed in) will always be in the form of name=value&name2=value2; we can treat it as a list. The UDF uses the listToArray function, treating the ampersand (&) as the list delimiter. This will return an array in which each element can be treated as a list as well as in the form of "name=value". We loop through each element of the array and grab the name portion. If it matches the value we want to change, we use the new value passed in. While we loop, we build up a new query string value that the UDF will return. Last but not least, if for some reason the value we want to change wasn't provided, we add it to the end. (QueryStringDeleteVar works in a similar fashion and can be found in Listing 2.)

That's it for this edition. As I said earlier, please send me your suggestions for UDFs, custom tags, or CFCs to highlight.

• Source Code