Defining and using method parameters

You pass data to a method by using parameters. To define a component method parameter, use the cfargument tag in the cffunction tag body. To define multiple parameters, use multiple cfargument tags. The tag names a parameter and lets you specify the following:

Whether the parameter is required
The type of data that is required
A default argument value
Display name and hint metadata for CFC introspection

Note: You can create CFC methods that do not use cfargument tags, for example, if you use positional parameters in your methods. However, most CFC methods use the cfargument tag.

Example: convertTemp.cfc

The convertTemp.cfc file consists of the following:

<cfcomponent>
   <!--- Celsius to Fahrenheit conversion method. --->
   <cffunction name="ctof" output="false">
      <cfargument name="temp" required="yes" type="numeric">
      <cfreturn ((temp*9)/5)+32>
   </cffunction>

   <!--- Fahrenheit to Celsius conversion method. --->
   <cffunction name="ftoc" output="false">
      <cfargument name="temp" required="yes" type="numeric">
      <cfreturn ((temp-32)*5/9)>
   </cffunction>
</cfcomponent>

Reviewing the code

The convertTemp CFC contains two methods that convert temperature. The following table describes the code and its function:

Code	Description
<cfcomponent>	Defines the component.
<cffunction name="ctof" output="false">	Defines the `ctof` method. Indicates that this method does not display output.
<cfargument name="temp" required="yes" type="numeric">	Creates the `temp` parameter of the `ctof` method. Indicates that it is required and that the expected value is `numeric`.
<cfreturn ((temp*9)/5)+32>	Defines the value that the method returns.
</cffunction>	Ends the method definition.
<cffunction name="ftoc" output="false">	Defines the `ftoc` method. Indicates that this method does not display output.
<cfargument name="temp" required="yes" type="numeric">	Creates the `temp` parameter of the `ftoc` method. Indicates that it is required and that the expected value is `numeric`.
<cfreturn ((temp-32)*5/9)>	Defines the value that the method returns.
</cffunction>	Ends the method definition.
</cfcomponent>	Ends the component definition.

Example: tempConversion.cfm

The ColdFusion page tempConversion.cfm is an HTML form in which the user enters the temperature to convert, and selects the type of conversion to perform. When the user clicks the Submit button, ColdFusion performs the actions on the processForm.cfm page. The file tempConversion.cfm, which should be in the same directory as convertTemp.cfc, consists of the following:

<cfform action="processForm.cfm" method="POST">
	Enter the temperature:
		<input name="temperature" type="text"><br><br>
	Select the type of conversion:<br>
		<select name="conversionType">
			<option value="CtoF">Celsius to Farenheit</option>
			<option value="FtoC">Farenheit to Celsius</option>
		</select><br><br>
	<input name="submitform" type="submit" value="Submit">
</cfform>

Example: processForm.cfm

The ColdFusion page processForm.cfm calls the appropriate component method, based on what the user entered in the form on the tempConversion.cfm page. It should be in the same directory as convertTemp.cfc.

<cfif #form.conversionType# is "CtoF">
	<cfinvoke component="convertTemp" method="ctof" returnvariable="newtemp"
		temp=#form.temperature#>
	<cfoutput>#form.temperature# degrees Celsius is #newtemp# degrees
		Farenheit.</cfoutput>
	<cfelseif #form.conversionType# is "FtoC">
		<cfinvoke component="convertTemp" method="ftoc"
			returnvariable="newtemp" temp=#form.temperature#>
		<cfoutput>#form.temperature# degrees Fahrenheit is #newtemp# degrees
			Celsius.</cfoutput>
</cfif>

Reviewing the code

The file processForm.cfm invokes the appropriate component method. The following table describes the code and its function:

Code	Description
<cfif form.conversionType is "CtoF">	Executes the code in the `cfif` block if the user selected Celsius to Fahrenheit as the conversion type in the form on the tempConversion.cfm page.
<cfinvoke component="convertTemp" method="ctof" returnvariable="newtemp" arguments.temp="#form.temperature#">	Invokes the `ctof` method of the `convertTemp` component, without creating an instance of the `convertTemp` component. Specifies `newtemp` as the result variable for the method. Assigns the temperature value that the user entered in the form to the variable `temp`, which is specified in the `cfargument` tag of the `ctof` method. When invoking the `ctof` method, the `temp` variable is assigned to the Arguments scope. For more information about variables and scope, see CFC variables and scope.
<cfoutput>#form.temperature# degrees Celsius is #newtemp# degrees Fahrenheit.</cfoutput>	Displays the temperature that the user entered in the form, the text "degrees Celsius is," the new temperature value that results from the `ctof` method, and the text "degrees Fahrenheit."
<cfelseif #form.conversionType# is "FtoC">	Executes the code in the `cfelseif` block if the user selected Fahrenheit to Celsius as the conversion type in the form on the tempConversion.cfm page.
<cfinvoke component="converttemp" method="ftoc" returnvariable="newtemp" temp=#form.temperature#>	Invokes the `ftoc` method of the `convertTemp` component, without creating an instance of the `convertTemp` component. Specifies `newtemp` as the result variable for the method. Assigns the temperature value that the user entered in the form to the variable `temp`, which is specified in the `cfargument` tag of the `ftoc` method. When invoking the `ftoc` method, the `temp` variable is assigned to the Arguments scope. For more information about variables and scope, see CFC variables and scope
<cfoutput>#form.temperature# degrees Fahrenheit is #newtemp# degrees Celsius.</cfoutput>	Displays the temperature that the user entered in the form, the text "degrees Fahrenheit is," the new temperature value that results from the `ftoc` method, and the text "degrees Celsius."
</cfif>	Closes the `cfif` block.

To run the example, display the tempConversion.cfm page in your browser. When you enter a value in the text box of the form, the value is stored in the form.temperature variable. Processing is then performed on the processForm.cfm page, which refers to the value as form.temperature. When you invoke either method, the cfinvoke tag assigns the value form.temperature to temp; temp is the argument specified in the cfargument tag of the appropriate method. The appropriate method in the convertTemp component performs the necessary calculations and returns the new value as newtemp.

For detailed reference information on the cfargument tag, see CFML Reference.

To access the parameter values in the component method definition, use structure- or array-like notation with the Arguments scope. The following example refers to the lastName argument as Arguments.lastname; it could also refer to it as Arguments[1]. In addition, you can access arguments directly using number (#) signs, such as #lastname#; however, it is better programming practice to identify the scope (for example, #Arguments.lastname#). Also, you can use Array- or structure-like notation, which lets you loop over multiple parameters.

For more information on the Arguments scope, see The Arguments scope.

To define parameters in the component method definition:

Create a new component with the following contents, and save it as corpQuery.cfc in a directory under your web root directory:

<cfcomponent>
	<cffunction name="getEmp">
		<cfargument name="lastName" type="string" required="true" 
				hint="Employee last name">
		<cfset var empQuery="">
		 <cfquery name="empQuery" datasource="cfdocexamples">
		 	SELECT LASTNAME, FIRSTNAME, EMAIL
		 	FROM tblEmployees
			WHERE LASTNAME LIKE '#Arguments.lastName#'
		 </cfquery>
			<!--- Use cfdump for debugging purposes. --->
		 <cfdump var=#empQuery#>
	</cffunction>
	<cffunction name="getCat" hint="Get items below specified cost">
	<cfargument name="cost" type="numeric" required="true">
		<cfset var catQuery="">
		<cfquery name="catQuery" datasource="cfdocexamples">
		 	SELECT ItemName, ItemDescription, ItemCost
		 	FROM tblItems
			WHERE ItemCost <= #Arguments.cost#
		 </cfquery>
			<!--- Use cfdump for debugging purposes. --->
		 <cfdump var=#catQuery#>
	</cffunction>
</cfcomponent>

In the example, the cfargument attributes specify the following:

The name attributes define the parameter names.
The type attribute for the lastName argument specifies that the parameter must be a text string. The type attribute for the cost argument specifies that the parameter must be a numeric value. These attributes validate the data before it is submitted to the database.
The required attributes indicate that the parameters are required or an exception will be thrown.
The Arguments scope provides access to the parameter values.

View comments in LiveDocs