Tag-Based UDFs

Tag-based UDFs are created using three tags:

• <cffunction>, which defines the function

• <cfargument>, which defines any function arguments

• <cfreturn>, which defines the function return value

Creating UDFs

UDFs are created using the <cffunction> tag; the function itself is placed between <cffunction> and </cffunction>.

Here is a simple example:

 <cffunction name="Tomorrow" returntype="date">   <cfreturn DateAdd("d", 1, Now())> </cffunction> 

Tomorrow() returns tomorrow's date (calculated by adding 1 day to today's date). The function is named using <cffunction>, and a return data type is defined. <cfreturn> returns the result.

Processing Arguments

Functions can accept arguments (parameters). When creating UDFs, you should use <CFARGUMENT> tags to enumerate every argument. Each argument should be named, and its type should be specified, so that ColdFusion can validate passed values automatically. In addition, if needed, arguments can be flagged as requiredagain, so that ColdFusion can perform automatic validation.

Here is an example:

 <cffunction name="Cube" returntype="numeric">   <cfargument name="num"               type="numeric"               required="yes">   <cfreturn num*num*num> </cffunction> 

Cube() returns the cube of a passed number. It takes a required argument (the number to be cubed) and returns the cube value.

<cfargument> takes an optional default value to be used if an argument is not specified. An example of this follows in the next section.

Local Variables

Within UDFs, it may be necessary to create variables for data storage. It is legal to do the following within a UDF:

 <cfset x=1> 

The above code works, but the variable that it creates will be in the calling page, not local to the UDF. So, if a variable named x already existed, the above code would overwrite it.

To create local variables (that is, local to the UDF), use the VAR prefix like this:

 <cfset var x=1> 

This way, references to x will refer to the local x, not the x in the caller code.

NOTE

To access variables in the caller code, use the VARIABLES prefix. Failure to do so will cause the local variable to be used (if it exists).

Here is a complete example:

 <!--- Is the browser IE? ---> <cffunction name="IsIE" returntype="boolean">   <!--- If no browser id passed, use current --->   <cfargument name="browser"               default="#CGI.HTTP_USER_AGENT#">   <!--- Init variable --->   <cfset var result="No">   <!--- Look for IE identifier --->   <cfif FindNoCase("MSIE", browser)>     <!--- Yep, got it --->     <cfset result="Yes">   </cfif>   <!--- Return result --->   <cfreturn result> </cffunction> 

IsIE() checks to see whether a specified browser is Microsoft Internet Explorer. It takes a browser ID string as a parameter, defaulting to the current browser by inspecting CGI.HTTP_USER_AGENT. A local variable named result is created (the VAR keyword ensures that it is local to the UDF) and is initialized to "no". If the text MSIE is found in the browser ID, result is set to "yes", then result is returned.

NOTE

Incidentally, to create an IsMozilla() function like the IsIE() used here, just modify the <cfif> to check the following:

 <cfif FindNoCase("mozilla", browser)       and not FindNoCase("MSIE", browser)>