cffunction

Defines a function that you can call in CFML. Required to defined ColdFusion component methods.

Attribute	Req/Opt	Default	Description
name	Required		A string; a component method that is used within the `cfcomponent` tag.
returnType	Required for a web service; Optional, otherwise.	any	String; a type name; data type of the function return value: any array binary boolean date guid - The argument must be a UUID or GUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x is a character representing a hexadecimal number (0-9A-F). numeric query string struct uuid - The argument must be a ColdFusion UUID of the form xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx where each x is a character representing a hexadecimal number (0-9A-F). variableName: a string formatted according to ColdFusion variable naming conventions. a component name - If the type attribute value is not one of the preceding items, ColdFusion treats it as the name of a ColdFusion component. When The function executes, it generates an error if the argument that is passed in is not a CFC with the specified name.
roles	Optional	"" (empty)	A comma-delimited list of ColdFusion security roles that can invoke the method. Only users who are logged in with the specified roles can execute the function. If this attribute is omitted, all users can invoke the method.
access	Optional	public	The client security context from which the method can be invoked: private: available only to the component that declares the method and any components that extend the component in which it is defined package: available only to the component that declares the method, components that extend the component, or any other components in the package public: available to a locally executing page or component method remote: available to a locally or remotely executing page or component method, or a remote client through a URL, Flash, or a web service. To publish the function as a web service, this option is required.
output	Optional	Function body is processed as standard CFML	Specifies under which conditions the function can generate HTML output. yes: The entire function body is processed as if it were within a `cfoutput` tag. Variables names surrounded by number signs (#) are automatically replaced with their values. no: The function is processed as if it were within a `cfsilent` tag If you do not specify this attribute, the function body is processed as standard CFML. Any variables must be in `cfoutput` tags.
displayname	Optional		Meaningful only for CFC method parameters. A value to be displayed in parentheses following the function name when using introspection to show information about the CFC.
hint	Optional		Meaningful only for CFC method parameters. Text to be displayed when using introspection to show information about the CFC. The `hint` attribute value follows the syntax line in the function description.

The cffunction tag can define a function that you call in the same manner as a ColdFusion built in function.

To define a ColdFusion component (CFC) method, you must use a cffunction tag. For information on using the cffunction tag.

The following example shows cffunction tag attributes for a simple CFC method that returns a ColdFusion Query object.

For information on using the cffunction tag for ColdFusion components, see Building and Using ColdFusion Components in Developing ColdFusion MX Applications.

If you specify a roles attribute, the function executes only if a user is logged in and belongs to one of the specified roles.

If you specify variableName for the returnType attribute, the function must return a string that is in ColdFusion variable name format; that is, the function must return a string that starts with a letter, underscore, or Unicode currency symbol, and consist of letters, numbers, and underscores (_), periods, and Unicode currency symbols, only. ColdFusion does not check whether the value corresponds to an existing ColdFusion variable.

Comments are no longer accepted for ColdFusion MX 6.1. ColdFusion 8 is the current version.

Comments

sanaullah said on Oct 16, 2003 at 7:41 AM :

here should be nice example about cffunction to use a package and component type.
Honestly we need indepth example rather than kids plays show

jrunrandy said on Oct 16, 2003 at 8:06 AM :

For more information, see the related discussion in the Developing ColdFusion MX Applications book:

UDFs: http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/udfs.htm
ColdFusion Components: http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/building.htm

Allen Manning said on Nov 18, 2003 at 8:27 AM :

Hey guys. Love the livedocs.

CFFunction gave me a confusing error when I tried to pass in a return type of integer:

<cffunction name="AddCustomer" access="public" returntype="integer">

it should say that 'integer' isn't a valid return type rather than the return type isn't of type integer.

HTH,
Take Care,
Allen Manning, Prismix Ltd.

jrunrandy said on Nov 18, 2003 at 8:44 AM :

This has been entered as bug 53756.

No screen name said on Dec 11, 2003 at 11:03 AM :

Why is that a bug? It should be a wanted feature to have the type Integer but Allen should use type Numeric until then.

jrunrandy said on Dec 11, 2003 at 11:15 AM :

Allen's comment has to do with the wording of the error message.

cfdevel said on Dec 16, 2003 at 11:10 AM :

Is returnType="void" still valid and supported? The MX doc includes it, but the MX 6.1 doc here does not (see MX doc page http://livedocs.macromedia.com/coldfusion/6/CFML_Reference/Tags-pt145.htm#2852457 )

Dross.2 said on Jan 9, 2004 at 8:20 AM :

I use void all the time w/o a hitch

michalg said on Jan 20, 2004 at 9:20 AM :

Got a problem with understanding returnType = a component name although I am not new to CF. Never seen it used (or didn't noticed). Could someone post an example of when to use it and how to use it?

No screen name said on Mar 7, 2004 at 10:23 AM :

Does this tag available in ColdFusion 5, I am sure not after spending 4 to 5 hours.

Along with the tag documentation Cold Fusion provides the versions as well on which these tag works!

jrunrandy said on Mar 8, 2004 at 5:47 AM :

I think the information you want is available from this link: http://www.macromedia.com/support/coldfusion/ts/documents/cfmlhistory.htm

fstrevisan said on May 17, 2004 at 1:02 PM :

The question about "void" return type still have no answer... I'm interested too: it's supported or not? It's deprecated? If I use it could I run into problems with newer versions of CF?

I miss the "history" part of this tag too, like in "cfinvokeargument", for example, we read: "ColdFusion MX: Added this tag." Several tags in the documentation doesn't have this history information (like cfargument, cfcomponent, etc). You could review it.

halL said on Jun 2, 2004 at 1:33 PM :

The void entry was incorrectly removed from the list of cffunction returnType attribute values.
You can use void as a returnType attribute value for all cffunction tags except for those where the access attribute is remote.
A function that is accessed remotely, such as by a web service, must return a value; otherwise, attempts to use the function remotely will cause errors.

zedfox said on Aug 6, 2004 at 8:52 PM :

I needed to know if we could pass more than 1 arguments and return long strings...wondered for a while, tried to search for examples for a while and then decided to give it a shot. Here is a function I used to populate a <select> menu:

in the main program sequence, here is how I call the function:

<cfoutput>#createoption("yan","Yankton")#</cfoutput>

in the function, I compare a form element called stationz with "yan" (or any other short form for a station). If they are equal, I return an <option> tag with "selected" property otherwise I simply return the <option> tag.

Here goes the function:

<cffunction name="createoption" returntype="string">
<cfargument name="whatstation" type="string">
<cfargument name="propercasewhatstation">

<cfif #stationz# eq #whatstation#>
<cfreturn "<option value='#whatstation#' selected>#propercasewhatstation#</option>">
<cfelse>
<cfreturn "<option value='#whatstation#'>#propercasewhatstation#</option>">
</cfif>
</cffunction>

This helped me reduce coding of 19 stations and it is going to help me for 180 more stations. I hope someone can get the idea from here and modify it to their own use.

Chirag Shukla.

awetiaue said on Sep 23, 2004 at 3:50 PM :

To return a component from cffunction, use the dot notation "folder.folder.cfcname". btw, slash "/" doesn't work here.

<cfcomponent>
<cffunction name="myMethod" returntype="myVersion.myPackage.myComponent" access="public">
<cfset result = CreateObject("component", "myVersion.myPackage.myComponent")>
<cfreturn result>
</cffunction>
</cfcomponent>

January26 said on Feb 14, 2005 at 11:13 AM :

Has any one noticed that if there is any character between CFOUTPUT or a line return and CFFUNCTION call an extra white space is added to the left of the CFRETURN value? If I set the return value to another variable, I get the output I expect. This is what I get when I run the code below. Anyone know why this is? I can find any documentation on this affect.

Some text here: THE TEST STRING
THE TEST STRING
Some text here:THE TEST STRING

<cffunction name="myFunction" returntype="string">
<cfargument name="myFunctionString" type="string" required="yes">
<cfset whatItDoes = UCase(myFunctionString)>
<cfreturn whatItDoes>
</cffunction>

<cfset temp = myFunction('the test string')>

<cfoutput>
Some text here:#myFunction('the test string')#<br>
#myFunction('the test string')#<br>
Some text here:#temp#<br>
</cfoutput>

jrunrandy said on May 24, 2005 at 10:00 AM :

FYI, a developer has reported that he had a problem using cfinvoke to
call a web service with multiple arguments, but was able to solve it
by using cfscript instead.

RanchMan said on Mar 8, 2006 at 4:34 PM :

If you are returning a string with the cffunction, make sure to set the output to false or characters will be added to the beginning of the string. http://www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=3&threadid=952492&highlight_key=y&keyword1=cffunction