User-Defined Functions in cfscript

User-Defined Functions in `<cfscript>`

To create a custom function using <cfscript>, you declare your function just as you would in JavaScript, using the function keyword. Like JavaScript, UDFs can accept and return values and can be embedded within other functions. And because UDFs support recursion, you can call each function from within the function itself.

Listing 12.12 shows an example of a UDF named TitleCase() that takes a string as its one argument and returns the string converted to title case (with the first letter of each word capitalized, and the rest in lowercase). TitleCase() can be called like any other function, as shown in the listing.

Listing 12.12. `UserDefinedFunction.cfm`Creating and Calling a UDF

 <!--- Author: Adam Phillip Churvis -- ProductivityEnhancement.com ---> <!--- Script-based user defined function (UDF) ---> <cfscript>   function TitleCase(rawSentence) {     var titleCaseSentence = "";     var numberOfListElements = ListLen(rawSentence, ", .;-:");     var currentElement = "";     var currentWord = "";     for(i=1; i LTE numberOfListElements; i=i+1) {       currentElement = ListGetAt(rawSentence, i, ", .;-:");       currentWord = UCase(Left(currentElement, 1));         if(Len(currentElement) GT 1) {           currentWord = currentWord &              LCase(Right(currentElement, Len(currentElement) - 1));         }       titleCaseSentence = titleCaseSentence & " " & currentWord;     }     titleCaseSentence = Trim(titleCaseSentence) & ".";     return titleCaseSentence;   } </cfscript> <cfoutput>   #TitleCase("i AM the very moDEL of a MODERN major general.")# </cfoutput>

Where to Define UDFs

You can define UDFs in two places: in the same ColdFusion template where the function is called, or in a separate .cfm file that is included in the same ColdFusion template where the function is called. Which technique should you use? It depends on how and where the function will be used.

If the user-defined function is used only in a single ColdFusion template, you can define the function directly in that template, typically at the top of the page. But since UDFs are built for reuse, you'll most likely have occasion to call the same UDFs from multiple templates. In that case, you'll need to define your UDF in an external .cfm file and then <cfinclude> that file in the ColdFusion templates that call the UDF.

But what if your application uses many different UDFs? To accommodate this, categorize your UDFs by the type of function they perform and then group them together in .cfm files that are named for each type of function. For example, if you have three functions that manipulate strings and seven functions that handle mathematical calculations, you might create two files named StringFunctions.cfm and MathFunctions.cfm and place the function definitions in these two files. Then, whenever a ColdFusion template needs to call a math function, you would simply <cfinclude> the MathFunctions.cfm in that template and then call the function wherever it was needed.

There are a few things you should keep in mind about user-defined functions:

The UDF name cannot match a built-in function name and cannot start with cf.
The number of arguments passed in the function call must be greater than or equal to the number of arguments declared in the function definition.
The var keyword initializes variables local to the function. All variables created inside a user-defined function should be declared as local function variables using the var keyword. You must declare all local function variables immediately after the function is declared and before any logic is executed. Arguments are already local to the function that defines them, so you don't need to separately declare them in the body of the function.

No discussion of user-defined functions would be complete without referring you to cflib.org, a Web site that contains hundreds of useful UDFs and libraries of UDFs available for free download and use. Do yourself a favor and head over there now for a quick tour of what they offer.