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.
<!-- 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" />
</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.
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.
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.
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.
$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:
<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.
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 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.
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>
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.