Your Rating: Results: PatheticBadOKGoodOutstanding! 0 rates

Description

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

Category

Extensibility tags

Syntax

See also

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

History

ColdFusion 10: Added the following REST attributes: restArgSource, restArgName}}

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.

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

restArgSource

Optional

 

One of the following:

  • path: Extracts parameters from the resource URL. URI path parameters are extracted from the request URI, and the parameter names correspond to the URI path template variable names specified in the restPath specified in cffunction. The default value cannot be used with path param.
  • query: Extracts parameters from URL query parameters. Mostly used with HTTP GET method. When using GET method to send data, the parameters and values are encoded into the URL. QueryParam is used to extract these values and assign them to the appropriate variables.
  • form: Extracts parameters from a form submission. It is used with HTTP POST method.
  • cookie: Extracts values form a cookie.
  • header: Extracts parameters from HTTP header.
  • matrix: Extracts parameters from matrix URI. For details, see http://www.w3.org/DesignIssues/MatrixURIs.html.
    If no value is specified, parameters are taken from the body of the request.Using cfhttp, you can send arguments in either form or body. For form parameter, the argument is consumed if you specify form as the value for restArgSource and for body parameter, if you do not specify restArgSource.
    While calling the service, if you pass the argument in body, in some scenarios, it is accepted as form. For example, <cfhttpparam type="body" value="arg=somevalue">. This is because, when you pass the form name-value pair through cfhttp or the body as "name=value", the body content is same, due to which REST service is not able to detect what is passed.
    In the service, if you expect body argument but while accessing the service through cfhttp, no argument in the body is passed, you will still receive the body argument as empty string.
    If you use this attribute, but do not specify the type attribute, string is considered by default as the type.

restArgName

Optional

 

The name that can be mapped to the argument name.
While calling functions, arguments are extracted from the incoming request. If restArgName is provided, it is searched in the restArgSource scope of the request to populate the argument. If not specified, argument name is searched.
If specified, then argument name has no impact. You can specify correct argument name so that it corresponds to the appropriate parameter. If the argument name passed to a REST service is not a valid Java identifier, for example, the name has hyphen (say arg-name), then you can use this attribute to map the argument name.

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: #arguments1#(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

Labels
  • None
  1. Nov 09, 2012

    CFSCRIPT EQUIVALENT

    component {
     
      /**
       *  This example defines a function that takes a course number
       *  parameter and returns the course description.
       *  @access public
       *  @returntype string
       *  @output false
       */
      function getDescription (required numeric Course_Number) {
        // Use the argument to get a course description from the database.
        var getDescription = new Query(datasource="cfdocexamples");
        var sql = "SELECT Descript
          FROM Courses
          WHERE Number = :Course_Number";
          
        LOCAL.getDescription.addParam(name="Course_Number", value=ARGUMENTS.Course_Number, cfsqltype="cf_sql_integer");
        
        var Description = LOCAL.getDescription.execute(sql=LOCAL.sql).getResult();
        
        // Specify the variable that the function returns.
        return LOCAL.Description.Descript;
      }
     
    }
  2. Dec 18, 2013

    Using the arguments scope as an array: #arguments1#

    That should of course be

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


Searching ColdFusion English Documentation