Harness and Section forms - Adding a section

Section

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

A section include can be referenced by property. At runtime, 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.

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.

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

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 to open the tool. See Using the Condition Builder to configure dynamic form actions.

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 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 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"

Click Label to add a caption. Enter the caption in the Label field and define the appearance of the text by selecting a label format.

Select Header to add a header to the included section and the Container Settings options display.

Optional. Clickto open the Image Library landing page and select an image to include on the left side of the header.

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".

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 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 to create a new when condition or review an existing when condition.

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

• 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 an expand icon () or collapse icon () that marks an area below the bar that users can expand or collapse (hide).
• 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.)

Appears when the Header type is Collapsible.

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

• 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.

Note: As a best practice, define custom styles in the skin.

• Cell width— Type the desired cell width in pixels.
• Cell height— Type the desired cell height in pixels.
• Cell read-write class — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode.
• Cell read-only class — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode.
• Cell inline class — Type CSS code to define an inline style. As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

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 if you want 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.

This field appears 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 runtime, 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 PDN 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.

Appears 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.

Field

Description

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 to create or open the section.

Click ( ) to enter parameters for the section.

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 setmessage 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.

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.

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. See Skin form — Components tab — Layouts — Containers.
• If additional formats are defined in the skin, then Otherdisplays 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. See About legacy headers in Skin form — Components tab — Layouts — Containers for more information.

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.

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 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 to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Appears when you select Conditional Visibility and enter a simple expression in the field that displays.

Select the Run visibility condition on clientcheck 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.

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 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.

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.

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 PDN How to configure non-blocking UI using Asynchronous Declare Pages (ADP).

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 to review or create the activity rule.

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 to open the tool. See Using the Condition Builder to configure dynamic form actions.

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.

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.

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 to review or create the privilege rule.

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 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.

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.

Optional. Clickto open the Image Library landing page and select an image to include on the left side of the header.

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".

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 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 to open the tool. See Using the Condition Builder to configure dynamic UI actions.

Select one of the following header styles. This field does not appear if the Format value is No Format, Hidden, Hidden Sub, Custom, or Outline.

This field does not appear in container and harness panels.

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.