The <cfparam> tag is probably one of the simplest and most commonly used tags in the CFML language and yet in the legacy app I am currently working it was virtually unused. So today I going to do a quick introduction to the different ways this tag can be used for those developers who do not know how to use it.

What Does CFParam Actually Do

The adobe livedocs explanation of the cfparam tag really hits the nail on the head, however I want to place emphasis on a particular part of this explanation that in my experience often gets overlooked.

Tests for the existence of a parameter (that is, a variable), validates its data, and, if a default value is not assigned, optionally provides one.

Not only does the <cfparam> tag allow us to test for a variables existence and assign a default value, it also allows us to perform validation of the value stored within the variable.

Syntax

Before we do some examples, lets first look at the syntax. The only required attribute is the name attribute, all the others are optional depending on how you wish to use the tag. For a detailed explanation of the different attributes you should visit the CFParam CFML Reference Page

<cfparam 
      name = "parameter name" 
      default = "value" 
      max = "value" 
      min = "value" 
      pattern = "regular expression" 
      type = "data_type">

Usage 1: Require A Variable

The simplest usage of cfparam is to require a variable to be defined. If we specify the scope in the variable name then the variable must exist within that scope, otherwise is must exist in one of the scopes which ColdFusion checks when scope is not explicitly named.

If the required variable does not exist then an application error is thrown, which you then need to manage with your error handling mechanism.

Require A Form Variable

To require that a form variable with the name "test1" is defined:

<!--- Require form variable test1 be defined --->
<cfparam name="form.test1">

Require A Variable

To require that a variable named "test2" exists in some scope simply omit the scope part of the variable name.

<!--- Require a variable test2 be defined in some/any scope--->
<cfparam name="test2">

ColdFusion checks the following scopes in this order to try find the variable test2:

1. Function Local (if inside a function) or Thread Local (if inside a thread)
2. Attributes (if inside a thread)
3. Query
4. Variables
5. CGI
6. Cffile (if an applicable CFFile tag was used)
7. Url
8. Form
9. Cookie
10. Client (if client variables are enabled)

Note that the following scopes are not checked by CF when the scope part is omitted:

• Server
• Application
• Session
• Request
• Attributes
• Error

For more information on the order in which CF checks the different scopes for a variable when scope is not explicitly named, Adam Tuttle wrote a good article on the order of precedence of ColdFusion scopes with notes on changes with CF8 to CF9

Usage 2: Supply A Default Value

If instead of throwing an error when a variable does not exist you wish to provide a default value then simply add the default attribute to the tag.

<!--- 
      If the variable form.test3 does not exist 
      then create it with a default value of "hello" 
--->
<cfparam name="form.test3" default="hello">

Usage 3: Type/Value Validation

Finally we get to the part of the cfparam tag which often gets overlooked...type and value validation.

Type Validation

It is worth mentioning that the type attribute of the cfparam tag is much more specific than the equivalent attribute in the cfargument. Here you can specify integer,float,guid,credit card etc etc. This can be really useful in the right situation.

<!--- Verify that a variable test4 exists and contains an integer --->
<cfparam name="test4" type="integer">

Range Validation

Does what it says on the box, checks if a variable is between two values.

<!--- Verify that a variable test5 exists and contains a value in the range 1 to 10 --->
<cfparam name="test5" type="range" min="1" max="10">

Pattern Validation

If neither type or range validation works you can always use some regex magic.

<!--- Verify that a variable test6 exists and contains a string matching the following pattern --->
<cfparam name="test6" type="regex" pattern="([a-z])">

In Conclusion

I know most of this is old news to most developers, but we were all new once and hopefully will be of help to any new cfml devs.

On that note, if you are new to cf I suggest you try out the new learn cf in a week website.