Understanding Functions

---

To understand what functions do and how they're useful in your templates, this section starts by looking at one of the most commonly used functions in the ColdFusion MX arsenal, Left(). The Left() function is used to display a specified number of characters beginning at the left of a string, so you often use it when you have a long string but only want to display the first few words or letters.

For example, assume that you've used <cfquery> to retrieve titles of developer seminars from a database. You want to display these titles on a page, but they're so long that they cause problems with your page design. One solution is to use Left() to truncate the seminar titles to a specific number of characters, say 50. The following code example assumes that the seminar titles have been previously retrieved by a query named get_seminar_titles and that they're found in a field called title:

<cfoutput query="get_seminar_titles">      #Left(title, 50)#[...]<br> </cfoutput>

Note that the ellipse in the brackets is not a special ColdFusion element. It's a literal ellipse in brackets that shows the reader that the titles have been truncated. Depending on the contents of your database, the preceding code might create output like the page shown in Figure 50-1.

Figure 50-1: Using Left() to truncate text strings

Like most ColdFusion MX functions, Left() accepts one or more items as input, and then it generates something as output. In the preceding example, the input consists of the two items within the parentheses: the variable title, which tells Left() the variable you want to truncate, and the number 50, which tells Left() how many characters to display, starting from the left side of the string.

Note 

When you're displaying the output of a function within a <cfoutput> section, you use hash marks around the entire function, not around the variable name itself:

<cfoutput> #Left(name, 3)# </cfoutput>

When you use a function within a CFML tag the hash marks usually aren't required:

<cfif Left(name, 3) is 'Mr.'>

Not all ColdFusion MX functions accept or require the same parameters, however. To illustrate, consider another commonly used function, DollarFormat(), which you use when you have a numeric variable you want displayed as a monetary value. For example, say that you're building an auction site in which users can enter a bid into a form box, hit Submit, and see the results of their bid. Some users may enter just the numeral 3; another may enter 9.5 (showing one decimal place) or 12.00 (showing two decimal places). To maintain consistency in the way these values are displayed, you could use DollarFormat() on the form's action page to standardize the way the user's input is displayed:

<cfoutput> Your Bid: #DollarFormat(form.user_bid)# </cfoutput>

This would cause any number the user typed into the form to display as currency, with a dollar sign and two decimal places:

$3.00 $9.50 $12.00

Note that unlike Left(), the DollarFormat() function accepts only one element — either a number or a variable containing a number.

The remainder of this chapter introduces you to several of the most commonly used functions and gives examples you can use in your templates. There obviously isn't space to cover all of ColdFusion MX's 200-plus functions here, so you should refer to the Macromedia product documentation for a complete list.

Tip 

ColdFusion MX also enables you to design your own functions to handle custom tasks not covered by its existing tag library. For more information, check your ColdFusion MX documentation for details on user-defined functions.

---