when JavaServer Page tag

Use the when tag to conditionalize a segment of HTML or XML, whether used for display, user input or correspondence. Use it to control whether stream processing includes, or omits, parts of HTML text under conditions that you determine. You can base the conditions on Boolean values returned by properties, Java methods, or when condition rules.

Examples

Example A. Using the test attribute, you can check the value of a text property using the Java == operator.

<!-- does the property .Color have the exact value RED? -->
<pega:when test=".Color == 'RED' " >
	... other HTML code here ...
</pega:when >

Example B: Assume an HTML rule contains the following HTML segment:

<!-- When this work item has resolved properties set -->
<pega:when name="HasBeenResolved" >
	<font class="dataLabelStyle">Resolved by</font>
	<pega:reference name=".pyResolvedUserID" />&nbsp;
</pega:when >

This when tag references a when condition rule named HasBeenResolved. At run time, if this rule evaluates to true, the output HTML contains the text "Resolved by" followed by the ID of the user who resolved the work item.

Complete syntax

In the syntax presentations below:

• Square bracket characters [ and ] surround optional parts of the tag. Do not type the brackets.
• JSP delimiters <pega: and </pega: mark the start and end of the tag.
• Replace any text in italics with your choice of value of that type.

<pega:when
	[name="When rule" ]
	[java="<%=expression %>"]
	[test="keyword"]>
HTML segment to include if true
</pega:when >

Exactly one attribute — test, name, or java — must appear.

<pega:when java="<%= !tools.getProperty("OperatorID.pyPwdVerify").getMessages().equals("") %>"></pega:when>

<pega:when test='$save(mysymbol)!="foo" '>
<!-- yes -->
</pega:when>

Referencing a when condition rule with the name attribute

Use the name attribute to identify a when condition rule. At run time, the system determines the Applies To key part of the when rule from the Applies To key part of the current rule, and uses rule resolution to locate the when rule.

When you save the current rule, the system confirms that the when condition rule you referenced is found.

The $mode-input and $input-enabled keywords

Two boolean keywords useful in control rules are available if an active property reference appears at the current position in the source HTML. These Booleans let you conditionalize stream processing based on the stream processing context.

• The $MODE-INPUT keyword is true when all of the following are true:
  • The current stream is an input-enabled stream.
  • The keyword is part of the processing of a <pega:reference > tag that specifies the INPUT option, with or without a stream name value.
  • The current property identified in the <pega:reference > tag is modifiable.
• The $INPUT-ENABLED keyword indicates that this HTML stream accepts input. This keyword is normally true, unless it falls within the scope of a <pega:include > tag that uses the NOINPUT mode.

For example:

<pega:when test="!$mode-input">this area is read-only </pega:when>
<pega:when test="$mode-input"> this area may allow input </pega:when>
<pega:when test="$input-enabled">this area may allow input</pega:when>

The $mode-display keyword is deprecated for new development; use !$mode-input instead.

Using when tags with choose

To implement more sophisticated testing and conditional operation in a stream rule, use a when tag within a choose tag. The otherwise tag, used only within a choose tag body, implements a none-of-the-above choice. See JavaServer Page Tags — choose.

Using a When rule

Use the name attribute to identify a when condition rule. At run time, system determines the Applies To key part of the when rule from the Applies To key part of the current rule, and uses rule resolution to locate the when rule.

When you save the current rule, the system confirms that the when condition rule you referenced is found.

The When condition rule is evaluated at run time on its own primary page, which may not be the primary page of the HTML or other stream rule. Review the Pages & Classes tab of the when condition to find its primary page. You can temporarily change the base page of the HTML rule during stream processing using the withPage tag.

Using PublicAPI methods

Use the test attribute to condition the output HTML on the results of these PublicAPI methods:

To determine whether a property value is presented as an input field, use the isModifiable PublicAPI method, which returns True if the property is modifiable. The underlying Java code determines whether a specific property is modifiable or not.

<pega:when test="$THIS:isModifiable" >
	<input type="text">
</pega:when>

To determine whether a property is scalar, use the isScalar PublicAPI method. Only scalar property references can be displayed or input in HTML.

<pega:when test="$THIS:isScalar" >
	<input type="text">
</pega:when>

To determine whether the current active property is a special property, use the isSpecial PublicAPI method:

<pega:when test="$THIS:isSpecial" >
	<input type="text">
</pega:when>

Evaluating a Java expression

Use the java attribute within the when JSP tag to evaluate a boolean Java statement. Enclose the java statement within the normal JSP delimiters <% and %>

For example:

<pega:when java=
"<%= tools.getParamValue("one").
	equalsIgnoreCase(tools.getParamValue("two")) %>">
	<H1>Update <p:r n=".pyID" /> <p:r n=".pyLabel" /> </H1>
</pega:when>

Working with more than one condition

If your JSP tag contains more than one expression, you can combine them using standard Java logical operators. Examples:

&& is the AND operator

<pega:when test="Monday && Morning" >
	do something
</pega:when>

|| is the inclusive OR operator

<pega:when test="VIP || NewCustomer" >
	do something
</pega:when>

! is the NOT operator

<pega:when test= ".customerID !=18" >
	do something
</pega:when>

Use only one of these operators in the Java statement. Expressions involving multiple operators or parentheses are not supported in the test attribute.

JavaServer Page Tags