Harness and section forms - Adding a section

Harness and Section forms - Adding a section

You can add a section to a layout, a region, another section, or a cell in a layout. Reusing sections achieves modularity, ensures a uniform appearance, and reduces the number of rules that you need to maintain and update when you revise user forms or portals.

You can add a section in one of the following ways:

  • Layout cell – Embed one section and render it in a layout cell. The section must be in an inherited class of the section containing the layout. If embedded in a repeating layout, the section must be in an inherited class of the layout. The section is not displayed in a wireframe. You cannot directly edit a section in a layout cell; open the rule to edit it. For more information, see Harness and Section forms – Adding a layout.
  • Section – Include one or more sections within another section. A wireframe appears around the included section, which is labeled Section Include. From the section's header, you can open the rule, and if enabled, use check in/check out features.
  • Flow action – Reference one section to create the basic flow action layout. For more information, see About flow actions.
  • Harness container – Include one or more sections to create the basic container layout. The section's header and format are configured in the container's property panel. A wireframe appears around the included section. From the section header, you can open the rule, and if enabled, use check in/check out features. You can include other sections in the container section, which are formatted in their own properties panels. See Harness form — Adding a container.
  • Harness panel – Include one section and render it in the panel. The section is not displayed in a wireframe. You cannot directly edit a section in a panel; open the rule to edit it. For more information, see Harnesses — Adding a panel set.

Embedding a section in a layout cell

To embed a section in a layout cell:

  1. Do one of the following:
  • Click the Structural list and select the Section control, and drag and drop the section onto the layout cell.
  • Select a section from the Application Explorer. Drag and drop the rule onto a layout cell.
  1. Click the View properties icon in the cell to open the Cell Properties panel and complete the General and Presentation tabs, and then click OK .

General tab

Section

Select or confirm the section you want to include. You can specify an existing section or type a new section name and click the Open icon to create or open the section.

A section include can be referenced by property. At run time, the section referenced in the property is added at to the UI. Select By Property Reference from the dropdown menu to refer to an existing property for the section.

Standard Parameters If standard parameters are:
  • defined for the section, then the parameters display here, along with a field into which you can enter the value that you want to pass to each parameter.
  • not defined for the section, then the No parameters to set message displays. To define parameters for the section, open the section and select the Parameters tab.

Alternatively, you can select the Pass current parameter page to pass the current parameter page to the section.

Page Context Select or confirm the page context for the section.
  • Use current page context — uses the class ( Applies To key part) of the current section
  • Use data page
  • Use clipboard page
  • Use page defined by property
Refresh Condition Optional: Enter a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators.

As a best practice, use the Condition Builder to edit expressions, or to trigger a refresh based on a property change or the addition or deletion of a row or column in a repeating layout. The editor also enables you to specify a pre-activity or data transform. Click the Gear icon to open the tool. For more information, see Using the Condition Builder to configure dynamic form actions.

Visibility

To control the visibility of the container, select one of the following:

  • Always : always visible
  • Condition (expression) : the region is visible under the specified condition. In the field that displays, select a condition or click the Gear icon to open the Condition Builder. 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 region is visible under the specified condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

If this section is to become part of navigation in a composite portal, you can make the header visible only when a specific space is the current space. Enter an expression here similar to the following:

pyCurrentSpace=="ASpaceName"
Then select the Run visibility condition on client check box.
Defer load contents Select this option if you want the system to retrieve only the data necessary for the current tab or accordion display. When another tab or accordion is selected, the system retrieves further data for it. With this option you can speed up the initial display of the page. To enable users to take actions, such as submit, on a work item while other content is still being loaded, configure sections to use defer loaded asynchronous declare pages.
Specify a pre-loading activity Optional. If Defer Load? is selected, you can specify an activity to run when the container is expanded by a click. This activity can compute property values and other aspects of the expanded container. As a best practice, instead of having multiple defer loaded sections with wrapper activities, create a deferred loaded wrapper section with the retrieval activity.
Associated privileges Select this check box to enable only users with specific privileges to view or update the section.
View privilege Optional. To restrict the presentation of this section (in read-only mode) to users who hold a specific privilege, select the Privilege Name key part of a privilege rule. Click the Open icon to review or create the privilege rule.
Update privilege

Optional. To restrict the presentation of this section (in read-write mode) to users who hold a specific privilege, select the Privilege Name key part of a privilege rule. Click the Open icon to review or create the privilege rule.

If a user holds the privilege in the View privilege field but does not hold the privilege identified in this field, the section appears in read-only format. In this case, default values for fields are not shown.

Container Settings  
Title Enter text to display in the header. You can also specify a property or field value.
Heading level Select a heading level from the drop-down menu. The container heading level generates semantic markup and makes the UI structurally understandable for assistive technology users. Heading level is available for all components that display headers.
Include icon with title Select to include an icon in the title bar.
Icon Optional: Click the Gear icon to open the Image Library landing page and select an image to include on the left side of the header.
Icon title If you want to display a tooltip when the user hovers the mouse pointer over the icon, type a text string within quotations, for example, "Select to view list" .
Body visibility Select one of the following to determine visibility:
  • Always : always visible
  • Condition (expression) : visible under the specified condition expression. In the field that displays, select a condition or click the Gear icon to open the Condition Builder. 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) : visible under the specified when condition. In the field that displays, select a when rule. Click the Open icon to create a new when condition or review an existing when condition.

As a best practice, use the Condition Builder to edit this field. For more information, see Using the Condition Builder to configure dynamic UI actions.

Header type Select the format to be used to present this header:
  • Bar — A horizontal bar that is always present. The section appears as a single horizontal strip; all labels and values visible on the strip.
  • Collapsible — A horizontal bar marked with icons that mark an area below the bar that users can expand or collapse.
  • Fieldset — Provides no header area, but a border around the contents of the layout with a single text label. (This produces HTML FieldSet and Legend elements.)
Expand when Displays when the Header type is Collapsible. Specify the When condition that must be met to expand the content.
Expanded on load Displays when the Header type is Collapsible.

Select to display the container expanded, rather than collapsed, on load.

Presentation Tab

Edit Options Select an edit mode for this control. The edit mode of the control, specified here, takes precedence over section and harness settings.
  • Auto — the control uses the edit mode of the section or harness in which it appears. If the section is set to Read Only, then the control is Read Only. If the section is set to Auto, then the control uses the edit mode of the harness. For example, a New harness is editable, while a Review harness is read only.
  • Editable — the control is editable, regardless of the edit mode of the enclosing layout.
  • Read Only (always) — the property value is presented in read-only mode always, or based on a when condition rule or client-side test, even when the enclosing layout is in read-write mode.
  • Read Only (expression) — the property value is presented in read-only mode based on an expression, even when the enclosing layout is in read-write mode.
  • Read Only (when rule) — the property value is presented in read-only mode based on a when condition rule.
Advanced Options  

Using the Section control

To include a section in other sections, drag and drop the Section control onto a section. As you move the pointer over existing frames or tabs, a yellow line indicates where the section will be dropped.

When you drop the Section control, the Section Include Form appears. Complete the fields as described:

Field Description
Page Context Select one of the following to set the context of the page – the basis for the fields (properties) within this section:
  • Use current context : Select to use the class ( Applies To key part) of the current section. By default, the class of the current section displays in the Class field.
  • Use other context : Select this check box to use a section that exists in a different class or identify a data page that contains the properties referenced in this section.

The Page Context field appears on the General tab of the section's properties panel.

Class Select a class that this section applies to. By default, the Class of the current section appears.

In most cases, select the name of the class that contains the work items that the section supports. Choose the class that is most specific to the application and its work items, rather than a general Work- class.

In special cases, a section can apply to a class derived from the Data-, Embed- or Assign- base class. For example, a section may display properties of the class Embed-OrderDetails, where the work item contains a Page List property named CustomerOrder that applies to the Embed-OrderDetails property.
Page This field displays when you select to Use other context as the Page Context.

Identify the name of the page that is the basis for fields (properties) within this section. If, at run time, no page with this name is found, all HTML output from this row is suppressed.

If you select a data page that has parameters, the parameters display:

  • To pass parameter values to the data page, press the down arrow beside the parameter and specify the Value that you want to pass to the data page.
  • When a data page accepts parameters and the parameter value uses a property reference, the page automatically refreshes with new items whenever the property value changes. No additional configuration is required. If you do not want the page to refresh automatically with new items whenever the property value changes, select the Disable automatic refresh check box.

If you enter a data page and are configuring a section that is defer loaded from an asynchronously loaded data page (ADP), make sure that all UI references to the data page are contained within the deferred UI. References to data page elements, such as Visible When, parameters to actions, or property displays (read-only or editable), will initiate synchronous data page load. UI display will be delayed until the data page is loaded. See Pega Community article: How to configure a non-blocking UI using Asynchronous Declare Pages (ADP).

If you enter a page that is not in this section's class inheritance path, enter the class in the Of Class field. The system updates the Pages & Classes tab when you click Save Changes to close this dialog.

Page names are case-sensitive, so be sure to match the case of the page name.
Disable auto refresh Displays when you specify, in the Page context field, a data page that has parameters and the parameter value uses a property reference.

When a data page accepts parameters and the parameter value uses a property reference, the page automatically refreshes with new items whenever the property value changes.

Select this check box if you do not want the page to refresh automatically with new items whenever the property value changes. This enables you to manually initiate refresh of a section; for example, if a user types text in a Search input box, you may want to disable auto refresh and explicitly refresh the section when the users presses Enter or clicks a button.
Section Select the name ( Purpose ) of the section that you want to include.

Using the Application Explorer

To include or reference a section in a new flow action, or a harness panel or container, drag and drop the control onto the tag <drag section here>, which appears on the flow action and harness layouts.

  1. Select a section from the Application Explorer, and drag and drop it onto a section, flow action, or harness container or panel.
  2. If you drag a section with an Applies To key that is not in this section's class inheritance path, the Pick/Add Page and Class dialog opens. Enter a page name in the Page Name field. If there are multiple classes or pages, use the radio buttons to select the page and class you want to use for this section. The system updates the Pages & Classes tab of the current section when you click OK to exit this dialog.

Editing the section Layout Properties

Field Description
Section

Specify the section that you want to use (the Purpose key part of the section). You can specify an existing section or type a new section name and click the Open icon to create or open the section.

Click the Gear icon to enter parameters for the section.

Standard Parameters If standard parameters are:
  • defined for the section, then the parameters display here, along with a field into which you can enter the value that you want to pass to each parameter.
  • not defined for the section, then the No parameters to set message displays. To define parameters for the section. select the Parameters tab.

Alternatively, you can select the Pass current parameter page to pass the current parameter page to the section.

Page context Select or confirm the page context for the section:
  • Use current page context — uses the class ( Applies To key part) of the current section
  • Use data page — in the field that displays, press the down arrow and select the data page. If the data page accepts parameters, then the parameters display here, along with a field into which you can enter the values that you want to pass to the parameters.
  • Use clipboard page — specify the clipboard page in the field that displays. Press the down arrow and select to reference:
    • a property on the primary page: select Primary. Primary, followed by a dot, displays in the field. Press the down arrow to select the property name that you want to use as the page context for the section.
    • a parameter on the parameter page: select Param. Param, followed by a dot, displays in the field. Press the down arrow to select the parameters you want to specify as the page context for the section.
  • Use page defined by property — specify the property that defines the page that you want to use.
Container format Select the format of the container that is to hold the content of the section. This choice affects the appearance of the header and body of the section.

The available formats depend upon the skin:

  • None – No header or subheader appears. In addition, no styles are applied to the body of this layout, including background, fonts, colors, padding, margins, and so on. The appearance of the body depends on styles of the enclosing control (which may be another layout).

    Accept this default value in most cases to help ensure vertical alignment of columns, even when multiple SmartLayouts appear on one form.

  • Default – The default container format, as defined in the skin.
  • If additional formats are defined in the skin, then Other displays in the list. Select Other and then specify the format that you want to apply in the Container style field.
  • If legacy header formats are enabled in the skin, they display in the list of available formats.

    As a best practice, avoid use of legacy header formats: Standard, Sub, Standard Hidden, Sub Hidden, Custom, Outline, A, B, C, D, Simple. Instead, replace legacy header formats with new container formats that create optimal markup and CSS.

Container style Displays if you specify Other as the Container format. Other displays only when additional container formats are defined in the skin.
HTML Appears if you specify Custom as the Container format. Identify the Stream Name (second key part) of an HTML rule that defines the content of the header.
Visibility To control the visibility of the section, select one of the following:
  • Always — The section is always visible
  • Conditional — The section is visible, depending upon a when condition rule or an expression. If you select this option, enter one of the following on the field that displays:
    • 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.

Run visibility condition on client? Displays when you select Conditional Visibility and enter a simple expression in the field that displays.

Select the Run visibility condition on client check box to cause dynamic execution of the condition each time the value of a property stated in the condition changes. This cannot be used if the expression is combined with a when condition rule.

Conditions are automatically re-evaluated when the user updates a property value. By default, controls that allow typing, such as Text Input, are evaluated when the user leaves the field. To re-evaluate conditions as the user types, use the Apply Conditions action with a Keyboard event. See Control Form — Completing the Control tab.

Display header and title Enter text to appear in the header or subheader. This text may include directives or JSP tags, such as <p:r > or <pega:lookup >.

If you plan to localize the application using this rule, choose the text carefully and limit the length to no more than 64 characters. When practical, choose a caption already included in a language pack, to simplify later localization. A field value rule with this text as the final key part is needed for each locale. See About the Localization wizard.

Defer load contents Optional: Choose this option to delay loading at runtime of the section content until the user clicks the header. Deferring enables users to start using other parts of the page rather than waiting for this section to load.
Note: Load deferring happens asynchronously and may cause errors when embedding a section inside another section.

To enable users to take actions, such as submit, on a work item while other content is still being loaded, configure sections to use defer loaded asynchronous declare pages. See Pega Community How to configure non-blocking UI using Asynchronous Declare Pages (ADP).

Specify a pre-loading activity Displays when you select the Defer load contents check box.

Select to run an activity prior to loading the section. Press the down arrow in the Activity field and select the activity that you want to run. Click the Open icon to review or create the activity rule.

Note: Pre-loading happens asynchronously and may cause errors when embedding a section inside another section.
Refresh condition Optional: Enter a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators.

As a best practice, use the Condition Builder to edit expressions, or to trigger a refresh based on a property change or the addition or deletion of a row or column in a repeating layout. The editor also enables you to specify a pre-activity or data transform. Click the Gear icon to open the tool. See Using the Condition Builder to configure dynamic form actions.

Run Data Transform Displays when you specify a Refresh condition.

Select to run a data transform prior to refreshing the section. Press the down arrow in the field that displays and select the data transform.
Run Activity Displays when you specify a Refresh condition.

Select to run an activity prior to refreshing the section. Press the down arrow in the field that displays and select the activity that you want to run.
Associated privileges Select to enable only users with specific privileges to view or update the section.
View privilege

Optional: To restrict the presentation of this section (in read-only mode) to those users who hold a specific privilege, select the Privilege Name key part of a privilege rule. Click the Open icon to review or create the privilege rule.

Update privilege

Optional. To restrict the presentation of this section (in read-write mode) to those users who hold a specific privilege, select the Privilege Name key part of a privilege rule. Click the Open icon to review or create the privilege rule.

If a user holds the privilege in the View Privilege field but does not hold the privilege identified in this field, the section appears in read-only format. In this case, default values for fields are not shown.

Container Settings Displays if you selected the Display header and title checkkox.
Title Optional: Type text to display in the header or subheader. This text may include directives or JSP tags, such as <p:r > or <pega:lookup >.

When you plan to localize the application using this rule, so the application can support users in various languages or locales, choose the text carefully and limit the length to no more than 64 characters. When practical, choose a caption already included in a language pack, to simplify later localization. A field value rule with this text as the final key part is needed for each locale. See About the Localization wizard.

Include icon with title Select to include an icon in the title bar.
Icon Optional: Click the Gear icon to open the Image Library landing page and select an image to include on the left side of the header.
Icon title If you want to display a tooltip when the user hovers the mouse pointer over the icon, type a text string within quotations, for example, "Select to view list" .
Body visibility Optional: Leave blank to present the body always. To control visibility of the body, enter or select one of the following:
  • 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.

Header type Select one of the following header styles. This field does not display if the Format value is No Format, Hidden, Hidden Sub, Custom, or Outline.
  • Bar – Provides a static horizontal bar at the top of the layout.
  • Collapsible – Provides a horizontal bar at the top of the layout, with the ability to expand or collapse to show or hide the layout when clicked.
  • Fieldset – Provides no header area, but a border around the contents of the layout with a single text label. (This produces HTML FieldSet and Legend elements).
Note: This field does not display in container and harness panels.

Tab Group properties panel

When you select a Header Style of Tabbed, the layout appears in a Tab Group wireframe. Select it to make it active and click the Gear icon in the header to open the Tab Group properties panel.

Complete the top field and General tab. There are no settings on the Advanced tab.

Top field

Field Description
Format 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.

General tab

Field Description
Tab Position Select the placement of the tabs at run time:
  • Top
  • Bottom
  • Left
  • Right

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

Tab Orientation 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.
Stretch Tabs Select to stretch the tabs 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.