CFML Reference
ColdFusion Functions

IIf

Description

Evaluates a Boolean conditional dynamic expression. Depending on whether the expression is true or false, dynamically evaluates one of two string expressions and returns the result. This function is convenient for incorporating a cfif tag in-line in HTML.

For general conditional processing, see cfif. For error handling, see cftry. For more information, see Developing ColdFusion MX Applications with CFML.

Return value

If result is True, returns the value of Evaluate(string_expression1); otherwise, returns the value of Evaluate(string_expression2).

Category

Decision functions, Dynamic evaluation functions

Syntax

IIf(condition, string_expression1, string_expression2) 

See also

DE, Evaluate

Parameters

Parameter	Description
condition	An expression that can be evaluated as a Boolean.
string_expression1	A string or a variable that contains one. Expression to evaluate and return if condition is True.
string_expression2	A string or a variable that contains one. Expression to evaluate and return if condition is False.

Usage

The IIf function is a shortcut for the following construct:

<cfif condition>

  <cfset result = Evaluate(string_expression1)>
<cfelse>
  <cfset result = Evaluate(string_expression2)>
</cfif>

The expressions string_expression1 and string_expression2 must be string expressions, so that they are not evaluated immediately as the parameters of IIf. For example:

IIf(y is 0, DE("Error"), x/y)

If y = 0, this generates an error, because the third expression is the value of x/0 (invalid expression).

ColdFusion evaluates string_expression1 and string_expression2. To return the string itself, use the DE function.

Note:   If you use pound signs (#) in string_expression1 or string_expression2, ColdFusion evaluates the part of the expression in pound signs first. If you misuse the pound signs, you can cause unexpected results from the IIf function. For example, if you use pound signs around the whole expression in string_expression1, and if there is an undefined variable in string_expression1, the function might fail, with the error 'Error Resolving Parameter,'

If a variable is undefined, ColdFusion throws an error when it processes this function. The following example shows this problem:

#IIf(IsDefined("Form.Deliver"), DE(Form.Deliver), DE("no"))# 

This returns "Error resolving parameter FORM.DELIVER".

To avoid this problem, use the DE and Evaluate functions in code such as the following:

#IIf(IsDefined("Form.Deliver"), Evaluate(DE("Form.Deliver")), DE("no"))#

This returns "no"; ColdFusion does not throw an error.

In the following example, LocalVar is undefined; however, if you omit pound signs around LocalVar, the code works properly:

<cfoutput>

  #IIf(IsDefined("LocalVar"), "LocalVar", 
    DE("The variable is not defined."))#
</cfoutput>

The output is:

  The variable is not defined.

The pound signs around LocalVar in the following code cause it to fail with the error message 'Error Resolving Parameter', because ColdFusion never evaluates the original condition IsDefined("LocalVar").

Here is another example:

<cfoutput>

#IIf(IsDefined("LocalVar"), DE("#LocalVar#"), DE("The variable is not defined."))#
</cfoutput>

The error message would be as follows:

  Error resolving parameter LOCALVAR

The DE function has no effect on the evaluation of LocalVar, because the pound signs cause it to be evaluated immediately.

Example

<h3>IIf Function Example</h3>
<p>IIf evaluates a condition, and does an Evaluate on string 
expression 1 or string expression 2 depending on the Boolean 
outcome <I>(True: run expression 1; False: run expression 2)</I>.</p>
<p>The result of the expression 
IIf( Hour(Now()) GTE 12, 
  DE("It is afternoon or evening"), 
  DE("It is morning"))
is:<br><b>
<cfoutput>
  #IIf( Hour(Now()) GTE 12, 
DE("It is afternoon or evening"), 
DE("It is morning"))#
</cfoutput>
</b>

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments