Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Using layouts to structure content in sections

Updated on May 3, 2020


Pega 7 provides a comprehensive solution for creating structured web design. This is achieved using advancements in the skin rule and through new modern layouts:

  • The skin rule provides settings that enable you to define the presentation elements of your user interface.
    • Presentation elements not only include typography, borders, backgrounds, and so on, but also include the presentation aspects of layouts.
    • These presentation aspects can determine the flow of content within the layout, among other things.
  • Layouts are structural elements that hold your content. Pega 7 includes new purpose-specific layout types for use in different situations.

The result is a structured user interface that is consistent, accurate, reusable, and easy-to-change when change is needed.

The best practice in creating modern user interfaces is to separate content from presentation—that is, separate the HTML from the CSS. In Pega's architecture, content resides in Sections and presentation resides in the Skin. Your skin determines how your content looks at runtime. 

Consistent Design and Presentation

Presentation includes the following:

  • Styling of the different controls, actionable elements, and supporting elements.
    • For example, you might make a button style with rounded corner and red background in the skin.
  • Defining the way items of a layout are positioned within the layout.
    • For example, width of the space allocated for label, versus width of space allocated to a field in a two-column layout.

​Pega 7 enables and enforces consistent user interface presentation and design throughout your application. For example, all forms will have consistent alignment of fields and captions. You define this stylistic uniformity once, in the application skin. When the UI is declared in the skin, it is much easier to reuse it and to change throughout your application.

Structured layout is also enabled at the screen level, through the hierarchy of screen harness, screen section (or screen layout and section), layout, and control.


The page content, which you define in your layouts, is comprised of:

  • Properties and the associated controls
  • Actionable elements like buttons and links
  • Supporting elements like icons, images and static text
  • Grouping of the above in layouts

Using Screen Layouts

Screen layouts determine the overall structure of your screen. They define the structure of a harness included in a composite portal. A harness can contain only one screen layout.

A screen layout is comprised of:

  • A main area
  • Adjacent regions, each identified by position: Header, Left, Right, and Footer


Each region in a screen layout can contain a single section. That section contains a layout, which in turn can hold various controls or included sections. Typically, the section that goes into the main area contains a dynamic container.


Screen layouts can also exhibit responsive behavior, which you can configure in the skin. Responsiveness enables the screen layout to adjust according to screen size, providing an optimal user experience on a desktop, tablet, and phone. 

Using Column Layouts

Column layouts are a type of dynamic layout that work similarly to screen layouts, but have more general applicability than screen layouts. With a column layout (which you define within a section), you select from a two- or three-column configuration as illustrated:


Column layouts work well where you have primary and related supporting content—for example, a product description in the main window and price and sizing details in the sidebar. Column layouts are designed so that the main area stretches to take up available space, whereas the sidebars are a set fixed width.

The width of sidebars is set in the skin. Column layouts can also be marked to be responsive. When the responsive breakpoint is reached, the sidebar shifts below the main area, providing the best viewing experience on a mobile device.

Using Dynamic Layouts

Dynamic layouts are standards-based layouts that enable you to provide an optimal user experience on a desktop, tablet, and phone. Dynamic layouts are key to how your sections are laid out and how they behave responsively. With dynamic layouts, you have the choice of determining the organization of controls on a section-by-section basis. The application skin provides a set of style formats for dynamic layouts. 

These style formats use one of two basic layout types:

  • Inline-grid - allows you to set the number of fields (or other items) that appear on the row of the dynamic layout.
    • The tab order through the controls is left to right and then to the next line. 
    • An inline-grid with one item per row is essentially a stacked layout.
    • You can choose to have up to 6 items per row.
  • Inline - allows you to add fields (or other items) in a row that flows "inline" like the words in a sentence.
    • The width given to each control is determined by the browser by default.
    • The items added to the layout appear next to each other until they run out of room, after which they wrap over to the next line. 
    • The tab order follows the controls row by row.

You can choose from four style formats (plus a default format), derived from the two layout types, and you can add custom formats (for example, up to 6 columns in a grid).


The Default layout can be changed to behave like any of the other formats. Any new dynamic layout has the format "Default" assigned to it, so it is best to configure Default to be your layout of choice.


A stacked grid is an inline grid with one column—one item on each row, aligned with the other items in the column. 


An Inline layout is not constrained by a grid, so each row can have a different number of items, and the items can be of different lengths.

Inline grid double

An inline grid with two columns—two items on each row, aligned with the other items in the column.

Inline grid triple

An inline grid with three columns—three items on each row, aligned with the other items in the column.

The appearance of a simple form in stacked, inline, and inline-grid double formats is illustrated here:


NOTEBoth inline and inline-grid configurations provide you the ability to display labels on the top or to the left of each field.

As mentioned above, the tab order for both inline and inline grid layouts goes from left to right, then down. If you have a situation where you would like to have the tab order go top-down
then to the next column, you would nest more than one dynamic layout, where each layout is a stacked layout, as illustrated:


Using the Skin to Format Dynamic Layouts

Dynamic layouts are the most flexible layout type. This is because they are completely declarative. This means that content is specified in the layout without details such as exact positioning and visual style. The skin determines the visual aspects of how the content is eventually displayed to the end user. 

The best practice in Pega 7 is to use dynamic layouts. The flexibility of dynamic layouts allows you to build to any design, and browsers handle them more efficiently. Because all the styling options are defined in the skin, changing a layout when change is necessary is a trivial task using the the configuration options in the skin:



The dynamic layout provides you with px, em, and % sizing. (These different measurements of size are a CSS facility; em is font spacing, px is a device-dependent absolute measurement.) It is usually best to use percent sizing so that contents are sized relative to their container. 

Defining the dynamic layout format as percent-based also automatically provides the UI some responsiveness; as the screen size reduces, the fields automatically resize to the width of the screen. Additionally, you can specify explicit responsiveness by defining responsive breakpoints for a dynamic layout in the skin.

Consider a simple example: Create a new two-column inline-grid layout using defaults for other settings (label position top and proportional column width). Call this layout "Basic Form". You can now create 10, 100, or 1,000 sections in your application, each of which contains a dynamic layout with the "Basic Form" format. Every one of the sections will be laid out the same.

Other Formatting

You can now experiment with changing alignment, label positioning, item spacing, or anything else. As soon as you save your skin, the change will be reflected in all sections that use this layout format.

Fields and labels remain perfectly aligned when you change the layout of fields or the position of labels. Fields take up more room automatically (since everything is percent-based) when the browser window is enlarged. If a label has insufficient space in a given layout, the text wraps to accommodate itself in the given space.

Nesting Dynamic Layouts

Dynamic layouts allow nesting, and this is a very powerful feature in structuring your sections. The reason for this is that a section with multiple fields typically demands organization into groups that are intuitive to the end-user. As we saw before, nested layouts are a convenient way to define columnar layouts—that is, where the tab order is top to bottom, then left to right.

Nesting permits you to add a dynamic layout inside another dynamic layout. In the example below, a default dynamic layout contains three nested inline-grid layouts, which group fields with different kinds of information (such as First Name and Last Name in the third one). As the layout changes responsively according to screen width—from desktop to tablet to smart phone—the nested layout preserves the logical grouping of fields as the layout shrinks and then stacks to accommodate the space. 

nested layout2.png

All dynamic layouts can use different standard formats or custom formats that can be added and saved under Style Formats in the skin properties.

Non-Dynamic Layouts

The following information is included for comparative purposes.

Smart Layouts

Smart Layouts have mostly been superseded by Dynamic Layouts. However, for very specific use cases, a smart layout might be a valid option. For example:

  • You are adding to pre-7.1 sections that for some reason or another cannot be converted to a dynamic layout. 
  • You have very fixed layout needs. (However, even these can be achieved with a dynamic layout.) 

Although smart layouts are almost as flexible and declarative as Dynamic Layouts at design time, their generated HTML is table-based, which is far less flexible at runtime. Dynamic layouts, on the other hand, are DIV-based, which makes them far more flexible at runtime as well.

Freeform Layouts

A freeform layout is a one-off page layout. It should never be used in Pega 7. What differentiates a freeform layout from a smart layout is that the columns of a smart layout have column types of Label, Field, or Spacer that align, while freeform layouts do not. 

Any changes to your design when using a freeform layout means that you have to fix every single section. This is primarily why you should never use a freeform layout. With a dynamic layout, you do not have to change a single section; the change is only restricted to the skin.

You can convert a freeform layout to a smart layout by changing the column type of all its columns.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us