Harness and Section forms —
Using the Condition Builder to configure dynamic UI actions

User interface events such as entering a property value in an input box or selecting a value from a Dynamic Select field can automatically trigger UI actions such as refreshing a harness, a section, hiding a property or section, expanding a layout, and so on. Changes on the server or the clipboard, for example, through a declarative expression or data transform, can also update the UI.

These actions make dynamic, interactive user forms and can improve user productivity and accuracy.

Use the Condition Builder to specify when rules and expressions that define the conditions that must be met before a UI action is triggered. This topic describes how to set conditions using the When condition fields: Visible When, Refresh When, and Read Only When.

For information on setting behaviors and actions for controls, see Control Form — Completing the Control tab.

Basics and where available

You control the conditions that trigger UI actions using When condition fields such as Visible When, Refresh When, and Read Only When, which are located on many UI element properties panels. You can enter:

• A when condition rule (except Refresh When)
• An expression that compares a property with another property or constant
• A pair of when rules, expressions, or in combination using AND/OR conditions

The Condition Builder provides an easy-to-use editing tool for defining conditions and helps ensure that expressions are valid. You access the Condition Builder by clicking the Gear icon next to a When condition field.

When condition fields are located on interface element property panels, which contain these When condition fields:

Note: Do not confuse When condition fields (such as Refresh When or Visible When) in property panels for UI components with when condition rules.

Without conditions, the default behaviors are as follows:

• Visible When — Always visible
• Expand When — The state of the layout (expanded or collapsed) when you save the Harness, Section, or Flow Action form is the state upon initial runtime presentation.
• Active When — The state of the layout (active or inactive) when you save the Harness, Section, or Flow Action form is the state upon initial runtime presentation.
• Read Only — Always read only mode (regardless of the enclosing layout mode)
  

Accessing the Condition Builder

To access the Condition Builder, do the following:

1. On the Layout tab of the section, harness, or flow action you are designing, select the element section include, layout cell, harness container, or layout ) that you want to configure and click the Gear icon next to the label.
   
   To use a Visible When condition in a layout cell, select Other Condition next to the Visible field. This displays the Condition field.
2. On the Properties panel, next to the Condition, Visible When, Refresh When, Expand When, Active When fields, or the Disabled Condition control parameter setting, click the Gear icon to open the Condition Builder dialog.

Building When conditions

This section describes how to build conditions for most when conditions. Refresh When conditions are described in the following section in this topic.

In the first drop-down list, choose the type of condition. Select When if you want to use a when condition rule, or select Expression if you want to use an expression.

When condition rule

Enter a when condition rule.

1. In the field to the right of the When drop-down, enter the When Name key part of a when condition rule. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule. Click the Open icon to review or create the rule.
2. In the next field, select Is True or Is False from the drop-down list.
3. Optional. In the second row, select And or Or if you wish to add another test condition (a when condition rule or an expression).
4. Click OK when you have completed the form.
   The when rule appears in the condition field on the property panel. If you defined a second expression or when rule, it appears to the right of the first when rule. When conditions always run on the server.

Expression

Configure an expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators.

1. In the fields to right of the Expression drop-down, use the property fields and the operator drop-down list to configure an expression.
   
   Enter one or more test conditions for the property value in the first field using one of the operators =, >, >=, <, <=, !=. You do not have to put quotation marks around constants; the system infers them automatically and adds them to the expression. You can enter constants and properties in either order. For example, Red=.color is valid.
   
   You can use embedded properties. Examples:
   
   .PageList(1).Property1 > 20
.PageGroup(“a”).Property1 > 20
.Page1.Property1 = 200
.PageList1(1).Property1 = “test”
   
   You can reference any number of levels in the hierarchy. For example:
   
   Page1.PageGroup(“a”).PageList(1).Property1 = “test”
   
   You cannot use a Date or DateTime type in a comparison. Function references are not supported.

2. Optional. In the second row, select And or Or if you wish to add another test condition (a when rule or an expression). If you use both conditions, the system inserts the && and || operators to denote your selection.
   

3. Click OK when you have completed the form. The expression appears in the When condition field on the Property panel.
   
   The Run on Client? check box appears beneath the When condition field if the expression can be run on the client. Complex expressions and When rules are not eligible.

   Select this check box if you want to cause evaluation and execution of the condition each time the value of a property stated in the condition changes. When the expression processes, all possible layouts are sent to the browser. Only the layout that matches the criteria is shown; any others are hidden. This enables you to switch layouts without a refresh.
   This option is not recommended if there are many conditionalized elements or the layout requires significant processing. For example, if you have four different versions of a grid that can appear at different times, you would not want to populate and generate all four, in order to render the page for the one that is visible.
   
   If the Run on Client? check box is not selected, then the expression is evaluated and the condition is dynamically executed when the form is initially presented and whenever the form is refreshed. Only the layout that matches the criteria is sent to the browser.
   

Run on server — Expressions must be run on the server if they contain:

— A when condition rule.

— Contains property and constant combined by boolean operators. Using a boolean property limits the options available for an expression.

Run on client — Expressions may be run on the client if:

— A when condition rule is not referenced.

And

— The expression has 4 or fewer properties and constants.

Example:

.pyProp2=“blue”&&.pyProp2>.pyProp3

See Constants in expressions — Constants for information on entering constants.

To invoke this processing, select Run On Client on the Properties panel.

Building Refresh When conditions

Refresh When conditions are expressions (see above) that can leverage the Changes or AddDelete keywords. To use the keywords:

Changes — Refreshes the section when a property value located anywhere on the harness changes. Select this option from the drop-down list and select a property. Optionally, use an OR condition with another AddDelete or Changes keyword.

AddDelete — Triggers an event when a row or column is added or removed from a repeating layout within the section ( Refresh When .pagelist() AddDelete). For example, an Order Summary that updates when the user edits the list of items in a shopping cart. Select this option from the drop-down list and select a Page List property. Optionally, use an OR condition with another AddDelete or Changes keyword.

Combining keywords with expressions

You can combine keywords with expressions using AND/OR conditions. For instance, you can specify that a property changes only when a check box is checked ( .Property1 Changes AND .Property2 = True). Other examples include:

.Property1 Changes AND .Property2 = "aaa"

.List1(). Property1 Changes OR .Property2 . List1()

.List2() AddDelete AND .List(2).PageGroup(Operator).name = "Scott"

(Preprocessing) Advanced

Available for Refresh When conditions.

Activity — Enter an activity with the Activity Name key part of an activity that may affect the content of the section to be redrawn.

Data Transform — Enter a data transform with the Name key part of a data transform that may affect the content of the section to be redrawn. See About Data Transforms.

To find the activity or data transform at run time, rule resolution uses the Applies To class of these rules.

If used in combination, the system processes the data transform first.

Using non-autogenerated controls to trigger UI events

If you are building a non-auto-generated control that can trigger a UI event, note the following prerequisites:

• A harness, section, or flow action saved in Version 5 or later that uses the SmartFrames layout and uses only JSP tags, not directives. Sections referenced with the rule also must use only JSP tags.
• A visible property presented on the runtime form in read-write mode.
• An event associated with a controlling property.
• A test condition associated with one or more controlled properties.

Notes

To implement a Refresh When condition, the Pega Platform uses AJAX technology to communicate between the browser client and the server at run time.

Open topic with navigation