Defining functions using the cffunction tag

The cffunction and cfargument tags let you define functions in CFML without using CFScript.

Note: This chapter describes how to use the cffunction tag to define a function that is not part of a ColdFusion component. For information on ColdFusion components, see Building and Using ColdFusion Components. For more information on the cffunction tag, see CFML Reference.

The cffunction tag function definition format

A cffunction tag function definition has the following format:

<cffunction name="functionName" [returnType="type" roles="roleList" 
      access="accessType" output="Boolean"]>
   <cfargument name="argumentName" [Type="type" required="Boolean"
      default="defaultValue">]
   <!--- Function body code goes here. --->
   <cfreturn expression>
</cffunction>

where square brackets ([]) indicate optional arguments. You can have any number of cfargument tags.

The cffunction tag specifies the name you use when you call the function. You can optionally specify other function characteristics, as described in the following table:

Attribute	Description
name	The function name.
returnType	(Optional) The type of data that the function returns. The valid standard type names are: any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, variableName, xml, and void. If you specify any other name, ColdFusion requires the argument to be a ColdFusion component with that name. ColdFusion throws an error if you specify this attribute and the function tries to return data with a type that ColdFusion cannot automatically convert to the one you specified. For example, if the function returns the result of a numeric calculation, a returnType attribute of string or numeric is valid, but array is not.
roles	(Optional) A comma-delimited list of security roles that can invoke this method. If you omit this attribute, ColdFusion does not restrict user access to the function. If you use this attribute, the function executes only if the current user is logged in using the `cfloginuser` tag and is a member of one or more of the roles specified in the attribute. Otherwise, ColdFusion throws an unauthorized access exception. For more information on user security, see Securing Applications.
output	(Optional) Determines how ColdFusion processes displayable output in the function body. If you do not specify this option, ColdFusion treats the body of the function as normal CFML. As a result, text and the result of any `cfoutput` tags in the function definition body are displayed each time the function executes. If you specify True or "yes", the body of the function is processed as if it were in a `cfoutput` tag. ColdFusion displays variable values and expression results if you surround the variables and expressions with number signs (#). If you specify False or "no", the function is processed as if it were in a `cfsilent` tag. The function does not display any output. The code that calls the function is responsible for displaying any function results.

You must use cfargument tags for required function arguments. All cfargument tags must precede any other CFML code in a cffunction tag body. Therefore, put the cfargument tags immediately following the cffunction opening tag. The cfargument tag takes the following attributes:

Attribute	Description
name	The argument name.
type	(Optional) The data type of the argument. The type of data that is passed to the function. The valid standard type names are any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, and variableName. If you specify any other name, ColdFusion requires the argument to be a ColdFusion component with that name. ColdFusion throws an error if you specify this attribute and the function is called with data of a type that ColdFusion cannot automatically convert to the one you specified. For example, if the argument `type` attribute is numeric, you cannot call the function with an array.
required	(Optional) A Boolean value specifying whether the argument is required, If set to True and the argument is omitted from the function call, ColdFusion throws an error. The default is False. The required attribute is not required if you specify a `default` attribute. Because you do not identify arguments when you call a function, all `cfargument` tags that specify required arguments must precede any `cfargument` tags that specify optional arguments in the `cffunction` definition.
default	(Optional) The default value for an optional argument if no argument value is passed. If you specify this attribute, ColdFusion ignores the `required` attribute.

Note: The cfargument tag is not required for optional arguments. This feature is useful if a function can take an indeterminate number of arguments. If you do not use the cfargument tag for an optional argument, reference it using its position in the Arguments scope array. For more information see Using the Arguments scope as an array.

Using a CFML tag in a user-defined function

The most important advantage of using the cffunction tag over defining a function in CFScript is that you can include CFML tags in the function. Thus, UDFs can encapsulate activities, such as database lookups, that require ColdFusion tags. Also, you can use the cfoutput tag to display output on the calling page with minimal coding.

Tip: To improve performance, avoid using the cfparam tag in ColdFusion functions. Instead, use the cfset tag.

The following example function looks up and returns an employee's department ID. It takes one argument, the employee ID, and looks up the corresponding department ID in the cfdocexamples Employee table:

<cffunction name="getDeptID" >
   <cfargument name="empID" required="true" type="numeric">
   <cfset var cfdocexamples="">
   <cfquery dataSource="cfdocexamples" name="deptID">
      SELECT Dept_ID
      FROM Employee
      WHERE Emp_ID = #empID#
   </cfquery>
   <cfreturn deptID.Dept_ID>
</cffunction>

View comments in LiveDocs