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.
Example A. Using the test attribute, you can check the value of a text property using the Java == operator. ZELEK 4/19/07
<!-- 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: ZELEK 9/30/02
<!-- When this work object has resolved
properties set -->
<pega:when name="HasBeenResolved" >
<font
class="dataLabelStyle">Resolved by</font>
<pega:reference
name=".pyResolvedUserID" />
</pega:when >
This when tag references a when condition rule named HasBeenResolved. At runtime, 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 object.
In the syntax presentations below:
[
and ]
surround optional parts of the tag. Do not type the brackets.<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.
Referencing a when condition rule with the name attribute
Use the name
attribute to identify a when condition
rule. At runtime, 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
VANDJ 12/16/02 Two boolean keywords useful in HTML Property 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.
$MODE-INPUT
keyword is true when all of the
following are true:
$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: OSMAE 12/2/08 syntax
<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>
In releases before V5.4, the keyword
$mode-display
indicated read-only output. The
$mode-display
keyword is deprecated for new development;
use !$mode-input
instead. Bug-8993 Bug-11595 ERNSG
2/14/08
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.
Use the name attribute to identify a when condition rule. At runtime, 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 runtime 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.
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>
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.