You are here: Building applications > Creating the User Experience > Harness and section forms - Adding a layout

Harness and Section forms - Adding a layout

About Harnesses

Layouts structure the content within sections. Every section contains at least one layout. You can choose from the following layout types:

Configure styles for layouts using the skin.

Note: Dynamic and column layouts are available only to user interfaces rendered in HTML 5 document type (standards mode). As a best practice, use these layouts when rendering applications in HTML 5 document type (standards mode).

1. Add a layout

You can add a new layout or copy an existing layout. You can add a layout above or below an existing layout.

  1. On the Design tab, select Layout group.
  2. Select Layout > Add a new layout.
  3. Drag the layout to the desired location on the Design tab. When the mouse pointer changes shape to indicate that you can drop the layout, release the mouse button.

Copy an existing layout

  1. Click to present the wireframe, right-click the existing layout, and then click Copy.
  2. Select the location in which you want to paste the layout, right-click and then select Paste Above or Paste Below.
    You can also use the toolbar controls to Cut , Copy and Paste existing layouts or select an existing layout and click Insert Row Above () or Insert Row Below () to add a new layout above or below the selected layout.

To delete a layout, select the layout and click the Delete Row button delete row, not the Delete Cell button.

2. Select a layout type

On the Set layout type dialog, select one of the following layout types and then click OK.

Layout

Description

Dynamic layout

See Adding a Dynamic layout for details.

Available only to user interfaces rendered in HTML5 document type (standards mode).

Select to create a dynamic layout. A dynamic layout is a DIV-based layout that allows for highly flexible display of content.

Dynamic layouts separate content and presentation. You add content, such as properties, controls, and other sections, to a dynamic layout within a section. You set the presentation of that content using dynamic layout formats specified in the skin. Each dynamic layout format defines the placement of the content in the section, the position of label, alignment, spacing etc. Changing the format in the skin automatically affects all sections using that format.

Dynamic layouts can be nested within other dynamic layouts. Dynamic layouts have responsive behaviors.

Select a dynamic layout format in the dynamic layout properties panel within a section or harness.

As a best practice, use the dynamic layout when rendering applications in HTML 5 document type (standards mode).

Smart layout

See About smart layouts for details.

Select to create a smart layout grid containing fixed-width, fixed-height column pairs. Each column pair is designed to hold one label and one field, typically for a Single Value property value.

Select one of the following templates or use a custom template as defined in the Skin rule:

  • Single — A single column pair.
  • Double — One column pair, a spacer column and a second column pair.
  • Triple — Three column pairs with two spacer columns.

The width and other style characteristics of these SmartLayout templates depends on the skin rule in use. To ensure consistent results when building harnesses and sections, for user forms, set the Using skin preference to the skin that application users are expected to use. You can change template widths, heights, cell padding, and other characteristics of Smart Layout templates in the Skin rule. See Skin form — Components tab — Layouts — Smart layouts.

The template cell height and widths are recorded in styles for the <TD> HTML element. If at runtime a cell contains an object that is explicitly larger than these values, browsers expand the table cell to attempt to display the entire object, overriding the fixed size restriction. The resulting display may vary somewhat by browser version.

Note: As a best practice, use dynamic layouts for new development. It is recommended that you upgrade existing smart layouts to take advantage of HTML5 capabilities including cross-browser and cross-platform compatibility, access to the latest HTML markup, and improved performance.

When you open a section with a smart layout, you'll see a guardrail warning and a suggestion to upgrade.

Click Update layouts for Designer Studio to update this layout instance to a dynamic layout.

Some smart layout configurations may not have a one-to-one correspondence with dynamic layouts and may require some manual modifications. Note the following:

  • Free form layouts and complex structures such as layout groups are not converted.
  • Inline styles on labels are removed.
  • The upgrade button is not available on Accordion and Tab Group smart layouts
Repeating

Select to create a layout that can present values from a Page List or Page Group property, a report definition or a data page. Select one of the following repeating layout types:

  • Dynamic --- To present each item from the source in the format specified in the skin. See Adding a Dynamic layout.
  • Column — To present each item from the source in vertical columns, typically with labels in the left most column. See Adding a Column Repeat layout.
  • Tabbed — To present each item from the source as a tab, typically with labels in the tab button. See Adding a Tabbed Repeat layout.
  • Grid — To present items in a spreadsheet format. See Adding a Grid layout.
  • Tree Grid — To present a tree navigation control in combination with a grid display of items. See Adding a Tree Grid layout.
  • Tree — To present items in a tree format that enables users to expand and collapse branches to find entries off current interest. See Adding a Tree layout.

Note: When displaying large amounts of data, the Grid, TreeGrid, and Tree layouts provide a display that, in most cases, is easier to implement and work with than repeating column or tabbed layouts. These layouts can display a custom skin; are cross-browser compatible; are sortable by column; and have fields that can be configured to be editable and localizable. See Skin form — Components tab — Layouts — Trees & grids.

Column layout

See Adding a Column Layout for details.

Note: Available only to user interfaces rendered in HTML5 document type (standards mode).

Select to create a column layout. Based on dynamic layout technology, column layouts provide the ability to display main content, such as a work item, alongside supporting content, such as an attachment.

Column layouts separate content from presentation.

You can add a column layout to a section and then add content, such as properties, controls, and other sections, to the column layout. Specify column layout formats in the skin.

Changing the format in the skin automatically affects all sections using that format. See Skin form — Components tab — Layouts — Column layouts.

Select a column layout format in the column layout properties panel in the harness or section.

Freeform

Select to create a freeform layout providing you with full control over the width and height of each cell. Specify the number of columns and rows you want to include in the freeform layout in the Cols and Rows fields.

As a best practice, use the dynamic layout when rendering applications in HTML 5 document type (standards mode).

4. Define the Layout Properties

Click (Magnifying glass) to open the Layout Properties panel.

Field

Description

Style format

Choose Single, Double, Triple, or Custom to control the number of column pairs in the Smart Layout.

Container format

Select a format for the Smart Layout container. You can create and modify formats in the skin. See Skin form — Components tab — Layouts — Smart layout.

Visibility

To control the visibility of the header, 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. Clickmagnifying glassto 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.

Note: 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.
Run visibility condition on client

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

Allow changes to columns

Optional. Selecting this check box converts this SmartLayout to a quasi-freeform layout. This gives you greater flexibility, enabling you to add and remove columns. Column restrictions remain in force, but you can change the type of any column, including the None (unrestricted) value, making it like a freeform column.

Row restrictions remain in force, but you can remove them if all columns have a None type. If all restrictions are removed, you can change the height of individual rows, or the width of individual columns. With this flexibility, you can support a wider variety of scenarios. However, columns will not automatically adjust when switching between Single, Double, and Triple layouts.

If you Allow Changes to Columns, you cannot undo this change.

See PDN article Using SmartLayout features — How to customize, use Merging Cells, and change Field Width.

Width

Select whether the width of columns in the table are to be set as a percent or in absolute pixels. Choose:

  • Pixels (Fit Content) — To have the column widths on the user form or flow action form match, in pixels, the column widths on the current rule form. (Internet Explorer may adjust column widths to avoid truncating values in the column.)
  • Pixels (Fixed) — To specify a column width exactly. The browser uses this width even when data values may be longer (after applying styles, margins, padding, and so on). The display may truncate a data value if the value is wider than width defined by the pixel value.
  • Fill (100% ) — To have the column widths on the user flow action form adjust to fractions of the total width of the user form or flow action form. For example, if you adjust the column on the rule form to be 25 percent of the total width, the column on the user form or flow action form will be 25 percent of the form width, and will grow or shrink if a user resizes the form.
  • Stretch-Spacer — To expand or contract the spacer widths so that the layout fits the entire form. The Field and Label column widths do not change. You cannot use this setting if the Smart Layout value is Single.

Caution: If you choose px-fixed and a property value at runtime is wider than width defined by the pixel value, the value is truncated, and users are unable to see the full value.

Display header and title

Select if you want to include a header.

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

Note: When 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.

Include icon with title

Select if you want to include an icon in the title bar.

Icon

Optional. Clickto 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 so that the body is always visible. To control visibility of the body, enter or select one of the following:

  • The When Name key part of a when condition rule. Click(magnifying glass) 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.

Run visibility condition on client

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

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.

Header type

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

Header Style

Description

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.)
Defer load contents

Appears when you select a CollapsibleHeader type.

Select to delay loading the section content at runtime 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).

Specify a pre-loading activity

Appears when you select a CollapsibleHeader type.

If Defer Load? is selected, you can specify an activity to be 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, create a defer loaded wrapper section with the retrieval activity (instead of having multiple defer loaded sections with wrapper activities.)

Creating and deleting rows and columns

Use the cell controls to add rows and columns, delete rows or columns, or merge cells.

In most cases, select an object in the layout before clicking an icon. Certain operations may be unavailable depending on your selection and the layout characteristics.

Control

Description

Delete the contents of a single cell (not a row or column)

Insert a new row before (above) the selected row

Insert a new row after (below) the selected row

delete row

Delete the selected row or layout

Merge right — Combine the selected cell and the cell to the right.

Merge down

Merge down — Combine the selected cell and the cell below it.

Unmerge All — Undo the previous merges.

The Insert column before , Insert column after , and Delete column operations are not available for Smart layout columns. They are available in freeform layouts.

Drag and drop operations

Up About Flow Actions

Up About Harnesses

Up About Sections