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.

JSP equivalent

The pega:when JavaServer Page tag provides a functionally identical capability. See JSP Tags — when.

Example

For example, assume an HTML rule contains the following HTML segment (excepted):

<!-- When this work has resolved properties set -->
  {when HasBeenResolved}
   &nbsp;
   <font class="dataLabelStyle">Resolved     by</font>&nbsp{.pyResolvedUserID}&nbsp
  {/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.

Complete Syntax

In the syntax presentations below:

• Square bracket characters [ and ] surround optional parts of the directive. Do not type the brackets.
• Curly brace characters { and } mark the start and end of the directive.
• Replace any text in italics with your choice of value of that type.

{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}

$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 Reference directive that specifies the INPUT option, with or without a stream name value.
  • The current property identified in the Reference directive 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 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}

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.

Using a When rule

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.

Using Java methods

Use the When directive to condition the output HTML on the results of these Java methods:

1. To mark invalid property values with a red X image (), 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}

Working with more than one condition

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}

Evaluating an expression

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.

Directives

Open topic with navigation