When directive |
Use the When directive 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 rules.
The pega:when JavaServer Page tag provides a functionally identical capability. See JSP Tags — when.
For example, assume an HTML rule contains the following HTML segment (excepted):
<!-- When this work has resolved properties set -->
{when HasBeenResolved}
<font class="dataLabelStyle">Resolved by</font> {.pyResolvedUserID} 
{/when}
This When directive references a when condition HasBeenResolved. If this condition is 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 directive. Do not type the brackets.{
and }
mark the start and end of the directive.{WHEN condition-specification}
HTML segment to include if true
{ELSEWHEN [condition-specification]}
HTML segment to include if false
{/WHEN [comments...] } or {ENDWHEN [comments...] }
The END
keyword is an alternative to the {/WHEN}
ending syntax:
{end}
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 an Include directive that uses the NOINPUT=
keyword.For example:
{when !$mode-input} this HTML is presented read-only {endwhen}
{when $mode-input} this HTML is presented allowing input {endwhen}
Your When directive can reference a when condition rule (Rule-Obj-When rule type). Enter the name of the when condition after the When keyword.
{when ExceedsSpeedLimit}
enter your HTML here
{endwhen}
The When condition rule is evaluated at runtime on its own primary page, which may not be the primary page of the HTML rule. Review the Pages & Classes tab of the when condition to find its primary page. You can temporarily change the base class of the HTML rule during stream processing using the With directive.
Use the When directive to condition the output HTML on the results of these Java methods:
1. To mark invalid property values with an image of a red X, or to respond to invalid property values in any other way, use the isBad
method.
Properties are invalid if the user's input does not match the expected input or if a message, indicating an error, is associated with the property.
{when $THIS:isBad}
<img src="/WebWB/images/redflag.gif
id="PegaRULESErrorFlag">
{endwhen}
2. To determine whether a property value is presented as an input field, use the isModifiable
Java method, which returns True
if the property is modifiable. The underlying Java code determines whether a specific property is modifiable or not.
{when $THIS:isModifiable}
<input type="text">
{endwhen}
3. To determine whether a property is scalar, use the isScalar Java method. Only scalar property references can be displayed or input in HTML.
{when $THIS:isScalar}
<input type="text">
{endwhen}
4. To determine whether a property is a special property, use the isSpecial method, which returns true if the property is special.
{when $THIS:isSpecial}
<input type="text">
{endwhen}
If your directive contains more than one condition, you can combine them using standard Java logical operators. For example,
&& is the AND operator:
{when Monday && Morning}
do something
{endwhen}
|| is the inclusive OR operator:
{when VIP || NewCustomer}
do something
{endwhen}
! is the NOT operator:
{when .custID !=18}
do something
{endwhen}
Use the Java directive with the When directive to evaluate an expression. For example:
{WHEN
{%tools.getParamValue("one").equalsIgnoreCase(tools.getParamValue("two"))%}}
<H1>Update {.pyID}{.pyLabel}</H1>
{ELSEWHEN}
<H1>Review {.pyID} {.pyLabel}</H1>
{endWHEN}
If the two parameters are equal, the heading on the form is "Update" followed by the work item ID. Otherwise, the title is "Review" followed by the work item ID.