View comments | RSS feed
Contents > CFML Reference > ColdFusion Tags > cfparam PreviousNext

cfparam

Tests for a parameter's existence, tests its data type, and, if a default value is not assigned, optionally provides one.

Variable manipulation tags

<cfparam 
   name = "param_name"
   type = "data_type"
   default = "value">

cfcookie, cfregistry, cfsavecontent, cfschedule, cfset

Attribute

Req/Opt

Default

Description

name

Required

 

Name of parameter to test (such as "Client.Email " or "Cookie.BackgroundColor "). If omitted, and if the parameter does not exist, an error is thrown.

type

Optional

any

The parameter data type:

  • any: any type of value
  • array: an array value
  • binary: a binary value
  • boolean: a Boolean value
  • date: a date-time value
  • guid: a Univerally Unique Identifier that follows the Microsoft/DCE standard, as follows:
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" where `X' is a hexadecimal number.
  • numeric: a numeric value
  • query: a query object
  • string: a string value or single character
  • struct: a structure
  • UUID: a ColdFusion Universally Unique Identifier, formatted `XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXX', where `X' is a hexadecimal number. See CreateUUID.
  • variableName: a string formatted according to ColdFusion variable naming conventions.

default

Optional

Value to set parameter to if it does not exist.

You can use this tag to make the following tests:

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

Tip: To improve performance, avoid using the cfparam tag in ColdFusion functions, including in CFC methods. Instead, place the cfparam tags in the body of the CFML pages.

<!--- This example shows how to use CFPARAM to define default values for page
   variables --------> 
<cfparam name = "storeTempVar" default = "my default value">
<cfparam name = "tempVar" default = "my default value">

<!--- check if form.tempVar was passed --->
<cfif IsDefined("form.tempVar") is "True">
   <!--- check if form.tempVar is not blank --->
   <cfif form.tempVar is not "">
      <!--- if not, set tempVar to value of form.tempVar --->
      <cfset tempVar = form.tempVar>
   </cfif>
</cfif>

<body>
<h3>cfparam Example</h3>
<p>cfparam is used to set default values so thata developer does not have to 
check for the existence of a variable using a function like IsDefined.

<p>The default value of our tempVar is 
   "<cfoutput>#StoreTempVar# </cfoutput>"

<!--- check if tempVar is still the same as StoreTempVar
and that tempVar is not blank --->
<cfif tempVar is not #StoreTempVar# 
   and tempVar is not "">
      <h3>The value of tempVar has changed: the new value is
      <cfoutput>#tempVar#</cfoutput></h3>
</cfif>

<p>
<form action = "cfparam.cfm" method = "post">
   Type in a new value for tempVar, and hit submit:<br>
   <input type = "Text" name = "tempVar">
   <input type = "Submit" name = "" value = "submit">
</form>
Contents > CFML Reference > ColdFusion Tags > cfparam PreviousNext

ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6.1

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

Comments


Adam Cameron said on Jan 26, 2004 at 5:24 PM :
It is not made clear by the documentation that any code in the DEFAULT parameter <em>is</em> executed, <strong>even if the variable already exists</strong>. This becomes relevant if the default value calls a component method that might change the state of the component, or the state of something else within the system.

This stands to reason if one is to stop and think about it, I guess: but it's easy to never stop and think about it :-)

Adam
halL said on Feb 2, 2004 at 8:28 AM :
The following information is true and should be added in future releases of the documentaiton:

Any expression used for the default attribute will be evaluated even if the parameter exists. The result will not be assigned if the parameter exists, but if the expression has side effects, they will still occur.
nk151 said on May 20, 2004 at 10:50 AM :
There is a difference between 6.0 and 6.1 when using cfparam to create nested structs. The statement <cfparam name="session.a.b.c.d.e" default="1"> works fine on 6.1, creating a nested structure, the innermost element having the correct value of 1.

However, on 6.0, it doesn't properly create it, and will leave you with a "session.c.d.e" structure in place -- the a and b elements are not created. It appears that cfparam has some sort of maximum levels that it can cope with.
No screen name said on Nov 8, 2004 at 4:34 AM :
"numeric: a numeric value",
"date: a date-time value"
This page is supposed to document the <cfparam> tag.
Can you document which numeric values
and date-time values are considered valid? Please explain influence of the locale setting. Eg in some parts of the world 123,456,789.00 is not valid number.
mindtrap said on Jan 18, 2005 at 7:54 AM :
What is the order of scope when cfparam is used?

That is not stated.
mindtrap said on Jan 18, 2005 at 8:11 AM :
After some testing I discovered that it's:

1. variables
2. url
3. form

The following scopes are not checked:
- request
- session
- clients
- application

Can anyone confirm this?
Belikov said on Mar 8, 2005 at 2:25 PM :
It looks like cfparam does not set values to proper variable and can modify variable when you did not expect it to be modified.
I think it is a dangerous bug, that can make debugging a real hell.
Please consider the following code:

<code>
<cfset variables["a"] = 0 >

<cfparam name="a " type="string" default="2">

<cfoutput>'a'=#variables["a"]#<br></cfoutput>
<cfoutput>'a '=#variables["a "]#</cfoutput>
</code>

The result is "'a'=2 'a '=" and an exception: "Element a is undefined in a Java object of type class coldfusion.runtime.VariableScope referenced as"

However, if I modify this code as shown bellow:
<code>
<cfset variables["a"] = 0 >
<cfset variables["a "] = 1 >

<cfparam name="a " type="string" default="2">

<cfoutput>'a'=#variables["a"]#<br></cfoutput>

<cfoutput>'a '=#variables["a "]#</cfoutput>
</code>

The result is more intuitive: "'a'=0 'a '=1" and no exception thrown.
jrunrandy said on Mar 15, 2005 at 1:47 PM :
When you use a CFML structure and the square-bracket construct, the part inside the square brackets is any name you want - for example:

<cfset myStruct["Hello and Goodbye"] = 123 >

This creates an element in the structure myStruct named 'Hello and Goodbye'. The name includes the three words and two spaces.

ColdFusion makes the VARIABLES scope available as a structure. This means you can put anything into it - for example:

<cfset VARIABLES["Hello and Goodbye"] = 123 >

The VARIABLES structure now contains an element named 'Hello and Goodbye'.

However, you cannot use this element as a CFML variable because it has an illegal name because of the spaces. For example, this won't work:

<cfset VARIABLES.Hello and Goodbye = 456 >

Adding elements to the VARIABLES structure is legal, just like any structure.
Adding elements with any name is allowed, but this does not turn elements with illegal names into bona fide CFML variables.

In short - <cfset VARIABLES["anyname"] = somevalue> is not forbidden by the CFML language, but it is not a recommended way of coding CFML.
jrunrandy said on Mar 18, 2005 at 1:20 PM :
I described this issue to one of our developers and he entered bug 59937 for this.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6.1/htmldocs/tags-b13.htm