when JavaServer Page tag

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" >
   &nbsp;
   <font class="dataLabelStyle">Resolved by</font>
   &nbsp;
   <pega:reference name=".pyResolvedUserID" />&nbsp;
</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 item.

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.

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.

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>

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.

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>

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.