Adobe ColdFusion 8

Creating user-defined functions

Before you create a UDF, you must determine where you want to define it, and whether you want to use CFML or CFScript to create it.

Determining where to create a user-defined function

You can define a function in the following places:

  • In a ColdFusion component. If you organize your functions in ColdFusion components, you use the functions as described in Using ColdFusion components.
  • On the page where it is called. You can even define it below the place on the page where it is called, but this poor coding practice can result in confusing code.
  • On a page that you include using a cfinclude tag. The cfinclude tag must be executed before the function gets called. For example, you can define all your application's functions on a single page and place a cfinclude tag at the top of pages that use the functions.
  • On any page that puts the function name in a scope common with the page on which you call the function. For more information on UDF scoping, see Specifying the scope of a function.
  • On the Application.cfc or Application.cfm page. For more information, see Designing and Optimizing a ColdFusion Application.

For recommendations on selecting where you define functions, see the sections Using Application.cfm and function include files and Specifying the scope of a function.

About creating functions using CFScript

You use the function statement to define the function in CFScript. CFScript function definitions have the following features and limitations:

  • The function definition syntax is familiar to anyone who uses JavaScript or most programming languages.
  • CFScript is efficient for writing business logic, such as expressions and conditional operations.
  • CFScript function definitions cannot include CFML tags.

The following is a CFScript definition for a function that returns a power of 2:

<cfscript>
function twoPower(exponent) {
    return 2^exponent; 
}
</cfscript>

For more information on how to use CFScript to define a function, see Defining functions in CFScript.

Defining functions in CFScript

You define functions using CFScript in a manner similar to defining JavaScript functions. You can define multiple functions in a single CFScript block.

Note: For more information on using CFScript, see Extending ColdFusion Pages with CFML Scripting.

CFScript function definition syntax

A CFScript function definition has the following syntax:

function functionName( [argName1[, argName2...]] )
    {
        CFScript Statements
    }

The following table describes the function variables:

Function variable

Description

functionName

The name of the function. You cannot use the name of a standard ColdFusion function or any name that starts with "cf". You cannot use the same name for two different function definitions. Function names cannot include periods.

argName1...

Names of the arguments required by the function. The number of arguments passed into the function must equal or exceed the number of arguments in the parentheses at the start of the function definition. If the calling page omits any of the required arguments, ColdFusion generates a mismatched argument count error.

The body of the function definition must be in curly braces, even if it is a empty.

The following two statements are allowed only in function definitions:

Statement

Description

var variableName = expression;

Creates and initializes a variable that is local to the function (function variable). This variable has meaning only inside the function and is not saved between calls to the function. It has precedence in the function body over any variables with the same name that exist in any other scopes. You never prefix a function variable with a scope identifier, and the name cannot include periods. The initial value of the variable is the result of evaluating the expression. The expression can be any valid ColdFusion expression, including a constant or even another UDF.

All var statements must be at the top of the function declaration, before any other statements. You must initialize all variables when you declare them. You cannot use the same name for a function variable and an argument.

Each var statement can initialize only one variable.

You should use the var statement to initialize all function-only variables, including loop counters and temporary variables.

return expression;

Evaluates expression (which can be a variable), returns its value to the page that called the function, and exits the function. You can return any ColdFusion variable type.

A simple CFScript example

The following example function adds the two arguments and returns the result:

<cfscript>
function Sum(a,b) {
    var sum = a + b;
    return sum; 
} 
</cfscript>

In this example, a single line declares the function variable and uses an expression to set it to the value to be returned. This function can be simplified so that it does not use a function variable, as follows:

function MySum(a,b) {Return a + b;}

You must always use curly braces around the function definition body, even if it is a single statement.