Harness and Section forms
Adding a Tree layout

Field

Description

Select either a Property (default), list-type Data Page, or a Report Definition as the data source for the repeating grid. You cannot select a summary-type Report Definition.

If you select Report Definition as data source, you can configure a dynamic grid.

Optional: If the data results comprise more than a single page (approximately 20 rows of data), you may want to specify a traditional Paging format. This option is not available if the data source is a report definition.

The system retrieves a segment, known as a page, containing the number of rows defined in the Items per Page setting, from the total data set on the clipboard. It presents the page navigation controls in a format defined in this option. You can drag and drop rows within a page.
When you select a paging option, the paginate gadget (pyGridPaginator section) is automatically added to the right-most cell in Action Top. You can drag and drop the gadget onto any cell in an action area (do not drop into the repeating area).
Note: If the results produce less than one page, the paginate gadget does not appear at runtime.

The options are:

Note: When the data set is large and performance is an issue, you can populate the clipboard incrementally using the Paginate Activity on the Advanced tab.

Select one of the following options to control when the tree is visible:

• Always: The tree is always visible.

• Condition (expression): The tree is visible under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder.

  Note: You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

• Condition (when): The tree is visible under the specified condition. In the field that is displayed, select a when rule. Click the Gear icon to create a new when condition or review an existing when condition.

Select one of the following options to control when the row is visible:

• Always: The row is always visible.
• Condition (expression): The row is visible under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder.
• Condition (when): The row is visible under the specified condition. In the field that is displayed, select a when rule. Click the Gear icon to create a new when condition or review an existing when condition.

Select one of the following options to control when the row is refreshed:

• Never: The row is never refreshed.
• Condition (expression): The row is refreshed under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder.

Display header

Appears if Display grid header is selected. Select one of the following to control when the grid header displays:

• Always: The grid header is always visible.

• Condition (expression): The grid header refreshes under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder.

  Note:  You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

• Condition (when rule): The grid header refreshes under the specified condition. In the field that is displayed, select a when rule. Click the Gear icon to create a new when condition or review an existing when condition.

Appears if Display grid footer is selected. Select one of the following to control when the grid footer displays:

• Always: The grid footer is always visible.

• Condition (expression): The grid footer refreshes under the specified condition. In the field that is displayed, select a condition or click the Gear icon to open the Condition Builder.

• Condition (when rule): the grid footer refreshes under the specified condition. In the field that is displayed, select a when rule. Click the Gear icon to create a new when condition or review an existing when condition.

Optional. If authorized, you can provide a unique Test ID for use in your test suite in order to support better automated testing against any Pega application.

When creating a control that supports Test ID, the Test ID field is initially blank. Use a combination of numbers, letters, and underscores, or click the Generate ID button to create a time stamp as a unique ID. The attribute data-test-id is then generated for the selected element.

When you save an existing section, any supported controls that do not have a Test ID will have one automatically generated. You can override these with a custom ID at a later time.

Once generated, you can view your Test ID in HTML or display it in the Live UI panel.

You also have the option to have all controls that support Test IDs in a ruleset updated in bulk.

A standard, out-of-the-box developer role, PegaRULES:SysAdm4, includes the privilege for Test ID. To disable Test ID for this role, modify the pxTestID privilege.

The edit mode sets the default presentation and behavior configuration for a repeating grid, determining how users view and edit properties.

By default, each edit mode is configured with grid actions — events and associated actions. The default action for all edit modes is Click to Set Focus. If you do not want a grid to have focus, for example, a display-only grid, delete this grid action.

You can add, delete, or edit grid actions as desired; click the Gear icon next to Edit Mode to configure grid actions. See Completing the Control tab for a description of actions.

Note: When configuring actions in a repeating grid, select the actions from the Handle List Items category. These actions are pre-configured to act upon the rows of the grid.

You can configure sequential actions based on a single event for a repeating grid; for example, Click to Set Focus and Click to Edit Item. The actions are acted upon in the order specified. You can also set multiple actions based on different events; for example, Click to Set Focus and Double Click to Edit Item.

You can also configure Keyboard actions to enable users to navigate and access items in a repeating grid. For example, you can configure the Up and Down arrows to set focus to the previous and next rows in a grid, and the Enter key to open the selected item.

For more information about edit modes, see PDN article 26349 About repeating layout edit modes.

Note: The UI Gallery contains working examples of edit modes and grid actions. To view and interact with examples and review configurations, select Designer Studio > User Interface > UI Gallery and select Tree in the Repeating Layouts group.

Select one of the following Edit Modes. See Completing the Control tab for a description of actions.

The system uses existing grid actions to determine whether to set focus to new rows.

If you want to set focus from within a row in a repeating grid to an editable control outside of the grid, provide the full path to the property, beginning with the parent page, and represent it on the Pages & Classes tab of the layout containing the repeating grid.

For Modal Dialog and Embedded Pane, click the Open icon next to the field to open the template section used to render the layout. By default, the templates are standard rules .pyGridModalTemplate and .pyGridDetails. To create custom templates, copy these rules into your Applies To class. Do not change the Purpose.

Depending on the mode you select, you will see a different array of the following fields:

Appears if edit mode is Modal Dialog or Embedded Panel, or Read Only and Show Details is selected. Select or create the flow action that will provide the form for the modal dialog or detail area that appears when the user clicks a row.

Appears if the Edit Mode is Embedded Pane or Modal Dialog. Select to allow the user to view the flow action details in read-only mode, which prevents locking the work item when it opens.

Caution: Do not select this option if the flow action contains an editable grid. The user will be unable to perform work in it.

Select to allow users to move objects higher or lower on the display by dragging and dropping individual rows. Depending on the properties of the objects the rows represent, rows may be moved above or below other rows, or dropped into a row that can receive them to become child entries of that row.

Visual indicators provide clues about the process: a line appears between two rows in the list if that is where the row you have started dragging will appear if you release it. A row that can receive the row you have selected as a child will change background color. If your mouse pointer is over an area where you cannot drop the row you have selected, an indicator will remind you that the area is not a valid target. If you attempt to drop the row there, the display will remain unchanged.

Select to allow users to adjust the width of columns on the display by dragging individual columns to the left or right.

Check to allow users to click a row border and drag it beyond the Height setting in the Row Properties panel.

Select if you want an OnHover style for rows, changing the appearance of a row when the pointer hovers over it. You can set the hover text and background color in the Skin rule.

Note: The UI Gallery contains working examples of Row Hover. To view and interact with examples and review configurations, select Designer Studio > User Interface > UI Gallery and select Tree in the Repeating Layouts group.

Select to allow users to sort on a column in the grid. This setting applies to all columns. You can disable sorting for individual columns by clearing the Enable Sorting check box in a column's Cell Properties panel. Sorting is not available for columns containing images, or controls such as buttons or links.

If enabled, a tool tip appears at runtime when the user hovers the mouse pointer over the column header. The user can alternate the sort order (ascending/descending) by  clicking the header. Icons indicating ascending sort and descending sort appear to the right of the header label. You can use the Skin rule to replace the default icons.

Sorting is performed on all rows in the tree. If paging is enabled and the user changes the sort order, the tree view returns to the first page.

Select to allow users to show only those rows that match a column value filter. This setting enables filtering for all columns that include a property. You can set filter types or disable filtering for individual columns using the Filtering options in the Column Properties panel. This option is not available in Read/Write mode.

If a column can be filtered, a filter icon appears on the right side of the column's header cell. The user clicks the icon to display the filter pop-up menu. On the menu, the user selects the check box next to each property to include. The menus also contain filtering mechanisms suitable for the property types in the column as follows:

• Date types ( Date and DateTime) — Define a data range in the From and To fields.
• Text — Enter free-form text in the abc field.
• Numeric types (Integer, Decimal, and Double) — Define a range by entering numeric values in the greater than and less than fields.

When finished, the user clicks Apply. The filter icon changes to a filter-on icon indicating that a filter is applied to the column.

You can use the Skin rule to replace the default icons.

Note the following:

— Columns containing images, action controls such as buttons or icons, hidden controls (pxHidden), prompt select controls, and subsections cannot be filtered.

— Filtering on Text properties that are obfuscated in edit-mode return results based on unfiltered data. Filtering should be disabled.

— The following property types cannot be filtered:

• TextEncrypted
• Password
• TimeOfDay
• Identifier

If the filter does not produce results, a message appears. You can modify the message text in the section pyGridNoResultsMessage.

Appears if edit mode is Read Only. Select to allow the user to click a row and display its flow action details (Embedded Pane, Modal, and Expand modes) beneath the row in read-only mode. The user can expand multiple rows. Enter the flow action in the Flow Action field.

Appears if Show Details is selected. Select to display details for all rows when the user opens the form.

Select to specify the maximum height and width of the layout. Further fields appear:

Specify the column width of this column in pixels. You can also adjust the width of a column directly:

1. Click a vertical wireframe cell border.
2. Wait until the pointer shape changes, then drag the border.

The unlabeled Use at Runtime check box to the right of the width field is enabled by default and cannot be edited. This forces the Width value to be used by the browser at runtime, even when data values in this column or in other columns would otherwise cause the browser to present a wider or narrower column. Data values may sometimes wrap or appear truncated.

Appears if the Filtering check box is selected on the Repeat Grid panel. Select a filtering option for this column:

• Auto — displays a check box for each unique value and the Search or Date Range fields, depending upon the column data type. This is the default.
• Range/Search — displays only the Search or Date Range fields, depending upon the column data type. Use this option to enable Search or Date Range on columns in which the values are unique, for example, a description.
• None — no filtering is available on this column.

Label Column panel only. Appears and is selected if Sorting is selected on the Tree properties panel. Clear the check box to disable sorting on this column.

Optional. Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the Gear icon to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the Gear icon to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

1. Click a horizontal wireframe cell border.
2. Wait until the pointer shape changes, then drag the border.

The unlabeled Use at Runtime check box to the right of the width field is enabled by default and cannot be edited. This setting forces the Height value to be used by the browser at run time, even when data values in this column or in other cells would otherwise cause the browser to present a taller or shorter column.

• The When Name key part of a when condition rule. Click the Open icon to review or create the rule.
• Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

As a best practice, use the Condition Builder to edit this field. Click the Gear icon to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Note: This field does not appear if the value in the Control field contains an Action mode control such as pxButton.

Select a control to format the value in this cell. If left blank, the property uses the control (if any) in the Control field on the property form's General tab.

Many controls on the Basic and Advanced groups are associated with default controls, which appear in this field when you drag and drop a control into the cell. For example, the Button control populates the field with pxButton, the Text Area control with pxTextArea, and so on.

Appears only if the control is not auto-generated, or if an auto-generated control was configured using the Client Event Editor in a release before PRPC Version 6.3.

Click the Gear icon next to this field to display the Client Event Editor, where you can specify formatting conditions and actions for this field. For general information on this capability, see Harness and Section forms Help — Client Event Editor.

Note: This field does not appear if the value in the Control field contains an Action mode control such as pxButton.

Select one of the options presented. The default is Always.

• The When Name key part of a when condition rule. Click the Open icon to review or create the rule.
• Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

As a best practice, use the Condition Builder to edit this field. Click the Gear icon to open the tool. See Using the Condition Builder to configure dynamic UI actions

Select to make this a required field if the user adds data to the display.

Select to force the text in this column to wrap to additional lines if it is longer than the width of the column.

Selected by default, which prevent edits to this field. You can refine this control by selecting or creating a when rule in the Read Only Condition field that appears when you select this option.

• The When Name key part of a when condition rule. Click the Open icon to review or create the rule.
• Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

As a best practice, use the Condition Builder to edit this field. Click the Gear icon to open the tool. See Using the Condition Builder to configure dynamic UI actions

Specify the width of this column. Select the check box to the right of the field to lock the width to the value you have specified.

Clear the Set width during execution check box (unlabeled) next to the width field to allow the browser at run time to determine the width of this column based on the size of the column contents and the size of other columns. The width may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no WIDTH= attribute.) The Width value is used as you view the rule form, but not at run time.

For example, clear this check box if the cell is to contain a section that may be wide in some situations and narrow in others.

Select the Set width during execution check box to force the Width value to be used by the browser at run time, even when data values in this column or in other columns would otherwise cause the browser to present a wider or narrower column. If checked, data values may sometimes wrap or appear truncated.

Optional. Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the Gear icon to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

Enter a positive number for the height in pixels of this cell.

Clear the Set height during execution check box (next to the height field and (unlabeled) to allow the browser at run time to determine the height of this row based on the size of the row contents and the size of other rows. The height may vary from use to use depending on the contents of this cell and other cells. (When cleared, the generated HTML for this column includes a <TD> element with no HEIGHT= attribute.) The Height value is used as you update the rule, but not at run time.

For example, clear this check box if the cell is to contain a section that may be tall in some situations and short in others.

Select the Set height during execution check box to force the Height value to be used by the browser at run time, even when data values in this column or in other cells would otherwise cause the browser to present a taller or shorter column.

Optional. Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the Gear icon to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.

Select to display all the cell values in the row with the same style that the column heading uses. This is an alternative to individually selecting the Use Heading Styles check box for each column. This option is unchecked by default.

Field

Description

Select the format you want to apply to the tabs in the group. To configure the format's appearance, access the Components tab in the Skin and then select Tab in the Layouts area.

• Standard — Default format applied to all tab groups.
• Sub — Format suitable for sub-tabs.
• Other — A custom style that you create in the skin rule. When you select this option, enter the style name in the Style field.

Field

Description

Select the placement of the tabs at runtime:

• Top
• Bottom
• Left
• Right

If you select Left or Right, specify the horizontal or vertical orientation of the tabs in the Tab Orientation field

If you selected a left or right Tab Position, select to display tabs horizontally or vertically. Horizontal is the default. If you select vertical orientation, the tab title is rotated based on the tab position, left or right.

Select to stretch the horizontally or vertically to fit the available space. If the Tab Position is Top or Bottom, tabs stretch horizontally; if the Tab Position is Left or Right, the tabs stretch vertically.