Adobe ColdFusion 8

cfargument

Description

Creates a parameter definition within a component definition. Defines a function argument. Used within a cffunction tag.

History

ColdFusion 8: Added component as a valid value for the ReturnType attribute.

ColdFusion MX 7: Added the xml value of type attribute.

ColdFusion MX: Added this tag.

Category

Extensibility tags

Syntax

<cfargument 
    name="string" 
    default="default value" 
    displayname="descriptive name"
    hint="extended description"
    required="yes|no" 
    type="data type">

See also

cfcomponent, cffunction, cfinterface, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfreturn

Attributes

Attribute

Req/Opt

Default

Description

name

Required

 

String; an argument name.

default

Optional

 

If no argument is passed, specifies a default argument value.

displayname

Optional

name attribute value

Meaningful only for CFC method parameters. A value to display when using introspection to show information about the CFC.

hint

Optional

 

Meaningful only for CFC method parameters. Text to display when using introspection to show information about the CFC. The hint attribute value follows the displayname attribute value in the parameter description line. Use this attribute to describe the purpose of the parameter.

required

Optional

no

Note: All arguments are required when invoked as a web service, irrespective of how they are defined.

Specifies whether the parameter is required to execute the component method. The parameter is not required if you specify a default attribute.

  • yes
  • no

type

Optional

any

String; a type name; data type of the argument.

  • any
  • array
  • binary
  • boolean
  • component: the argument must be a ColdFusion component.
  • 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.
  • xml: XML objects and XML strings
  • 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.

Usage

This tag must be in a cffunction tag, before any other tags in the cffunction tag body.

Arguments that are passed when a method is invoked can be accessed from the method body in the following ways:

  • With shorthand syntax: #myargument#

    (This example accesses the argument myargument.)

  • Using the arguments scope as an array: #arguments[1]#

    (This example accesses the first defined argument in the cffunction.)

  • Using the arguments scope as a struct: #arguments.myargument#

    (This example accesses the argument myargument in the array.)

Example

<!--- This example defines a function that takes a course number parameter and returns the course description. --->
<cffunction name="getDescription">
    <!--- Identify argument. --->
    <cfargument name="Course_Number" type="numeric" required="true">
    <!--- Use the argument to get a course description from the database. --->
    <cfquery name="Description" datasource="cfdocexamples">
        SELECT Descript
        FROM Courses
        WHERE Number = '#Course_Number#'
    </cfquery>
    <!--- Specify the variable that the function returns. --->
    <cfreturn Description.Descript>
</cffunction>