Advanced UDF Use

The basic UDF syntax and use described thus far is typical of most UDFs that will be created. ColdFusion also supports some advanced UDF features that are worth reviewing.

Variable Parameter Lists

UDFs can access arguments that are not explicitly named. This is primarily of value in <cfscript>-based UDFs, as it is the only way to support optional arguments, but it can be used in tag-based UDFs too.

All UDF arguments, regardless of whether they are enumerated explicitly, are stored in an array named arguments. As such, arguments[1] always refers to the first passed argument, arguments[2] to the second, and so on.

An example of using arguments this way is to create a <cfscript>-based UDF that adds specified values. Consider the following UDF:

 <cfscript> function Sum() {  return ArraySum(arguments); } </cfscript> 

Sum() simply returns the sum of any values in the arguments array using the ArraySum() function. To add two numbers, you could use the following:

 <cfoutput> #Sum(2, 3)# </cfoutput> 

But because the UDF is not explicitly expecting two arguments, the following two calls will also work:

 <cfoutput> #Sum(2)# #Sum(2, 3, 4, 7)# </cfoutput> 

Scoping UDFs

UDFs are visible only when they are defined inside the calling page or included with <cfinclude>. You can, however, place UDFs within shared-scoped variables. After the UDF definition, you can copy the UDF into a shared scope simply by using the scope prefix:

 <cfscript> function functionName() { ... function definition ... } </cfscript> <cfset REQUEST.functionName=functionName> 

In this example, the function is put into the REQUEST scope. This means that any custom tags within the calling page will also have access to this UDF.

You also can create UDFs by using other shared scopes, such as SERVER and APPLICATION, if needed.

UDFs as Parameters

Because UDFs can be stored in variables, they also can be passed as parameters. This is used primarily in the creation of callback functions, where the name of a function is passed to a second function so that the first may make calls to the second when needed.

To pass a UDF as a parameter, simply specify its name (without parentheses) like this:

 #BuildMenu(menu, MenuFormat)# 

Here, BuildMenu() is a UDF, menu is menu text to be processed, and MenuFormat is a second UDF that is being passed to BuildMenu().

Code that is expecting UDFs as parameters can use the following two functions to check that they are what is expected:

• IsCustomFunction() checks whether a specified function is actually a UDF.

• GetMetaData() returns details about a function (the parameters it is defined to expect, what it returns, and so on) and can be used to check that a passed function is defined as intended.