User Interface Specialist

STUDENT GUIDE (v. 7.1)

  Copyright 2015
Pegasystems Inc., Cambridge, MA
All rights reserved.

This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information.
The document and product are protected by copyright and distributed under licenses restricting their use, copying,
distribution, or transmittal in any form without prior written authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the document may be made from time to time at the
discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request.
This document does not imply any commitment to offer or deliver the products or services provided.

This document may include references to Pegasystems product features that have not been licensed by your company. If you
have questions about whether a particular capability is included in your installation, please consult your Pegasystems service
consultant.

®
PegaRULES, Process Commander, SmartBPM and the Pegasystems logo are trademarks or registered trademarks of
Pegasystems Inc. All other product names, logos and symbols may be registered trademarks of their respective owners.

Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical
errors. This document or Help System could contain technical inaccuracies or typographical errors. Changes are periodically
added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described
herein at any time.

This document is the property of:

Pegasystems Inc.
1 Rogers Street
Cambridge, MA 02142
Phone: (617) 374-9600
Fax: (617) 374-9620
www.pega.com

Document Name: UIS_716_StudentGuide_20150910.pdf
 Date: 20150910
Table of Contents
Getting Started................................................................................................. 1
What Makes a Good UI....................................................................................................... 2

A Brief History of Responsive Web Design................................................................. 3

What Is User Experience............................................................................................... 4

Principles of Great User Experience............................................................................ 6

Content and Presentation.................................................................................................. 8

Introduction.................................................................................................................... 8

Separating Presentation and Content......................................................................... 9

Web Front End Code Basics.......................................................................................... 10

The CSS Box Model........................................................................................................ 13

Dissecting the UI.................................................................................................................. 16

Introduction.................................................................................................................... 16

Desktop Web UI Examples........................................................................................... 17

Mobile vs. Desktop Design........................................................................................... 23

Conclusion...................................................................................................................... 23

Pega 7 UI Basics............................................................................................... 24
UI Elements in a Pega Application.................................................................................... 25

Instruction...................................................................................................................... 25

Pega UI Structure in Building Screens......................................................................... 26

Pega UI Structure in Building Forms........................................................................... 29

Conclusion...................................................................................................................... 30

Pega UI Architecture........................................................................................................... 31

Introduction.................................................................................................................... 31

Pega UI Architecture...................................................................................................... 32

UI Stream Generation................................................................................................... 34

What Makes Pega UI Different..................................................................................... 35

UI Building Blocks............................................................................................ 36
Creating the First Form....................................................................................................... 37

Introduction.................................................................................................................... 37

Demo: Creating the Form with Simple Fields............................................................. 38

 Exploring the Rules Created......................................................................................... 39

Modifying the Display of Fields......................................................................................... 42

Introduction.................................................................................................................... 42

Significance of Controls................................................................................................ 43

Standard Controls.......................................................................................................... 45

Assigning Controls to a Field........................................................................................ 47

Rearranging Fields in the Form......................................................................................... 52

Introduction.................................................................................................................... 52

Adding New Layouts...................................................................................................... 53

Embed Layouts.............................................................................................................. 56

Set Headers.................................................................................................................... 58

Save as Sections............................................................................................................. 60

Conclusion...................................................................................................................... 61

Styling the Appearance of the Forms............................................................................... 62

Introduction.................................................................................................................... 62

Configuring the Presentation of the Form Layout..................................................... 63

Configuring the presentation of date controls.......................................................... 64

Configuring the Presentation of Other Input Controls Used in the Form.............. 65

Configuring the Presentation of Buttons Used in the Form..................................... 66

Designing Forms.............................................................................................. 68
Creating (Advanced) Forms................................................................................................ 69

Introduction.................................................................................................................... 69

Dynamic Layouts............................................................................................................ 70

Column Layouts............................................................................................................. 72

Including Layouts and Sections.................................................................................... 73

Sourcing List-Based Controls............................................................................................. 76

Introduction.................................................................................................................... 76

Standard List Based Controls....................................................................................... 77

Sourcing List Based Controls........................................................................................ 81

Populating Static Lists................................................................................................... 82

Populating Dynamic Lists.............................................................................................. 85

 Configuring an Autocomplete Control........................................................................ 87

Conclusion...................................................................................................................... 89

Use cases........................................................................................................................ 89

Control name................................................................................................................. 89

Radio button................................................................................................................... 89

Dropdown....................................................................................................................... 89

Autocomplete................................................................................................................. 89

Displaying Lists.................................................................................................................... 90

Introduction.................................................................................................................... 90

Displaying Lists............................................................................................................... 91

Sourcing Options for Lists............................................................................................ 93

Edit Modes of Grids....................................................................................................... 96

Configuration of Grid Features.................................................................................... 98

Conclusion...................................................................................................................... 100

Displaying Hierarchical Data.............................................................................................. 101

Introduction.................................................................................................................... 101

Data Model for Hierarchical Relationship................................................................... 102

Using Trees..................................................................................................................... 104

Using Tree Grids............................................................................................................ 106

Conclusion...................................................................................................................... 107

Using Layout Groups.......................................................................................................... 108

Introduction.................................................................................................................... 108

Explain the Concept of a Layout Group...................................................................... 109

Configuring a Layout Group......................................................................................... 110

Displaying Read Only Form................................................................................................ 113

Introduction.................................................................................................................... 113

Different Ways to Create Read-Only forms................................................................ 114

Setting Forms as Read-Only......................................................................................... 116

Conclusion...................................................................................................................... 117

Use To Present............................................................................................................... 117

Option............................................................................................................................. 117
 Separate sections.......................................................................................................... 117

When rules or Expressions........................................................................................... 117

Privileges......................................................................................................................... 117

Including section in a layout......................................................................................... 117

Including section in a harness...................................................................................... 117

Displaying Static Content................................................................................................... 118

Introduction.................................................................................................................... 118

Presenting Static Content and the Need for Enhanced Text Output...................... 119

Using Paragraphs........................................................................................................... 123

Using Rich Text Editor................................................................................................... 125

Conclusion...................................................................................................................... 126

Use To Present............................................................................................................... 126

Option............................................................................................................................. 126

Label................................................................................................................................ 126

Formatted Text and Other Controls............................................................................ 126

Paragraph....................................................................................................................... 126

Rich Text Editor.............................................................................................................. 126

Mimic a Sentence........................................................................................................... 126

Displaying Contextual Help................................................................................................ 127

Introduction.................................................................................................................... 127

Why Do We Need Contextual Help?............................................................................ 128

Using Controls................................................................................................................ 129

Using Smart Tip or Smart Info...................................................................................... 131

Styling Smart Tips and Smart Info and Using Action Controls................................. 134

Conclusion...................................................................................................................... 135

Use cases........................................................................................................................ 135

Control name................................................................................................................. 135

Tool tips.......................................................................................................................... 135

Placeholder..................................................................................................................... 135

Smart Tip......................................................................................................................... 135

Smart Info....................................................................................................................... 135

 Action control................................................................................................................. 135

UI Tools................................................................................................................................. 136

Introduction.................................................................................................................... 136

Using the Live UI Tool.................................................................................................... 137

Live UI Editing................................................................................................................. 143

Adding, Moving, or Deleting UI Elements Using the UI Gallery................................ 144

Using the User Interface Landing Page....................................................................... 148

Using the UI Kit............................................................................................................... 150

Other Tools..................................................................................................................... 151

Creating Dynamic UI........................................................................................ 154

What is a Dynamic UI?........................................................................................................ 155

Introduction.................................................................................................................... 155

Illustrate a Dynamic User Interface............................................................................. 156

Benefits of a Dynamic User Interface.......................................................................... 158

Conditionally Hide or Show Fields in a Form................................................................... 159

Introduction.................................................................................................................... 159

Configure Visibility......................................................................................................... 160

Refresh Condition.......................................................................................................... 163

Refresh Using an Action Set......................................................................................... 165

Actions on Controls............................................................................................................. 166

Introduction.................................................................................................................... 166

Events, Actions and Action Sets................................................................................... 167

Configure Action Sets with Multiple Events and Actions.......................................... 170

Available Events, Actions and Conditions................................................................... 172

Displaying Calculated Fields in a Form............................................................................. 175

Introduction.................................................................................................................... 175

The Change Tracking Mechanism................................................................................ 176

Using the Refresh Condition to Update Values on the Screen................................ 177

Using the Action Set to Update Values on the Screen.............................................. 178

Conditionally Display Fields as Read-only, Disabled or Required................................. 179

Introduction.................................................................................................................... 179
 The Difference Between Disable and Read-only....................................................... 180

How to Disable Fields.................................................................................................... 181

How to Make Fields Read-Only.................................................................................... 183

How to Make Fields Required...................................................................................... 185

Defer Loading Fields........................................................................................................... 186

Introduction.................................................................................................................... 186

Describe and Configure Lazy Loading......................................................................... 187

Defer the Loading of Part of a Page............................................................................ 188

Configure Paging............................................................................................................ 190

Cascading Relationships on List Based Controls............................................................. 193

Introduction.................................................................................................................... 193

Common Use Cases for Cascading Controls.............................................................. 194

Configuring Cascading Controls.................................................................................. 195

Grid Actions.......................................................................................................................... 197

Introduction.................................................................................................................... 197

Configure Action Sets on Grids.................................................................................... 198

Extend the Grid Update Mechanism........................................................................... 200

Configure Row Visibility and Refresh.......................................................................... 201

Presentation..................................................................................................... 202
Introducing the Styling Concept........................................................................................ 203

Introduction.................................................................................................................... 203

Presentation vs Content............................................................................................... 204

Presentation Layer in Pega 7........................................................................................ 207

Skin Rule......................................................................................................................... 210

Conclusion...................................................................................................................... 211

Skin Basics............................................................................................................................ 212

Introduction.................................................................................................................... 212

A Cascading Styling Pattern.......................................................................................... 213

Formats........................................................................................................................... 214

Mixins.............................................................................................................................. 217

Conclusion...................................................................................................................... 221
 Styling Layouts..................................................................................................................... 222

Introduction.................................................................................................................... 222

Dynamic Layouts............................................................................................................ 223

Nested Layouts.............................................................................................................. 229

Column Layouts............................................................................................................. 230

Layout Groups................................................................................................................ 232

Floats............................................................................................................................... 234

Conclusion...................................................................................................................... 235

Styling Controls................................................................................................................... 236

Introduction.................................................................................................................... 236

Controls........................................................................................................................... 237

Configuring Buttons...................................................................................................... 238

Configuring Links........................................................................................................... 242

Configuring Dropdowns................................................................................................ 244

Configuring Text Inputs & Formatted Text................................................................. 245

Conclusion...................................................................................................................... 245

Styling Grids......................................................................................................................... 246

Introduction.................................................................................................................... 246

Configuring Grids in the Skin Rule............................................................................... 247

Configuring Grids in the Section Rule......................................................................... 252

Conclusion...................................................................................................................... 253

Container Styling................................................................................................................. 254

Introduction.................................................................................................................... 254

Configure Containers in the Skin Rule........................................................................ 255

Conclusion...................................................................................................................... 259

Validating User Inputs..................................................................................... 260

Introduction to Validation.................................................................................................. 261

Introduction.................................................................................................................... 261

Server-side and Client-side Validation........................................................................ 262

What to Validate............................................................................................................. 263

Best Practices for Validation Design............................................................................ 266

 Client Side Validation.......................................................................................................... 267

Introduction.................................................................................................................... 267

Identify Mandatory Fields............................................................................................. 268

Property and Control Validations................................................................................ 271

Client-side Format Validation....................................................................................... 274

Validating Using Custom JavaScript............................................................................. 275

Conclusion...................................................................................................................... 276

Server Side Validation......................................................................................................... 277

Introduction.................................................................................................................... 277

Validate Rule................................................................................................................... 278

Edit Validate Rule........................................................................................................... 281

Edit Input Rule................................................................................................................ 283

Declarative Validation................................................................................................... 285

Table Type Validation.................................................................................................... 286

Conclusion...................................................................................................................... 287

Customizing Error Messages............................................................................................. 288

Introduction.................................................................................................................... 288

Types of Errors............................................................................................................... 289

Customize Error Messages in Harness....................................................................... 291

Customize Error Messages in Skin.............................................................................. 292

Conclusion...................................................................................................................... 293

Designing Screens............................................................................................ 294

UI Elements in a Screen...................................................................................................... 295

Introduction.................................................................................................................... 295

Using Live UI to Explore a Screen................................................................................ 296

Defining a Screen Layout.............................................................................................. 300

Using a Skin Rule for Screen Presentation................................................................. 302

Controlling Screen Displays.......................................................................................... 303

Using Browser Developer Tools................................................................................... 305

Creating Your Own Portal.................................................................................................. 307

Introduction.................................................................................................................... 307
 Portal and its Components........................................................................................... 308

Harness Used in Portals................................................................................................ 309

Dynamic Containers...................................................................................................... 311

Dynamic Containers in Layouts................................................................................... 313

Styling Portals................................................................................................................. 314

Building Personalizable Dashboards................................................................................ 316

Introduction.................................................................................................................... 316

Need for Personalizing Dashboards........................................................................... 317

Terminologies................................................................................................................. 319

Personalizing a Dashboard........................................................................................... 321

Configuring Widgets...................................................................................................... 324

Developer Setup Tasks.................................................................................................. 325

Publishing the Dashboard............................................................................................ 328

Navigation......................................................................................................... 329
Navigation Modes............................................................................................................... 330

Introduction.................................................................................................................... 330

Navigation Choices in Screens..................................................................................... 331

Navigation Choices in Forms........................................................................................ 332

Navigation Using Controls............................................................................................ 336

Using a Navigation Rule...................................................................................................... 338

Introduction.................................................................................................................... 338

Examples of Navigation Rule........................................................................................ 339

Configuring a Navigation Rule...................................................................................... 341

Configuring a Navigation Rule to Present the Context Menu.................................. 345

Conclusion...................................................................................................................... 345

Creating Menus................................................................................................................... 346

Introduction.................................................................................................................... 346

Configuring a Menu Control......................................................................................... 347

Presenting a Context Menu.......................................................................................... 350

Conclusion...................................................................................................................... 352

Embedding a Pega Application as a Gadget.................................................................... 353

 Introduction.................................................................................................................... 353

What is IAC?.................................................................................................................... 354

IAC Architecture in a Web Application........................................................................ 356

Developing Pega Composite Applications.................................................................. 358

Creating Gadget Code in Designer Studio.................................................................. 360

Configuring the Gadget................................................................................................. 361

Mobility.............................................................................................................. 362
Designing a Mobile Application......................................................................................... 363

Introduction.................................................................................................................... 363

The Concept of a Responsive User Interface............................................................. 364

Configuring Responsiveness in Portals....................................................................... 367

Configuring Responsiveness in Dynamic and Column Layouts............................... 369

Configure Responsiveness in Layout Groups............................................................ 373

Configuring Responsiveness in Grids.......................................................................... 375

The Concept of an Adaptive User Interface................................................................ 377

Configure an Adaptive User Interface......................................................................... 379

UI Readiness for Mobile Application........................................................................... 381

Mobile Specific Controls and Behaviors........................................................................... 383

Introduction.................................................................................................................... 383

The Address Map Control............................................................................................. 384

The Signature Capture Control.................................................................................... 390

The Attach Content Control.......................................................................................... 392

Configure an Application for a Mobile Experience.................................................... 394

Localizing Pega Applications........................................................................... 397

Creating a Localized Application....................................................................................... 398

Introduction.................................................................................................................... 398

Why Localize Your User Interface................................................................................ 399

Using Client and Browser Locale Settings.................................................................. 401

Overriding Locale Settings in Designer Studio........................................................... 405

Using Locale Settings on the Operator Record.......................................................... 408

 Translating Labels and Messages..................................................................................... 409

Introduction.................................................................................................................... 409

Creating Field Values for Localization......................................................................... 410

Creating Messages for Localization............................................................................. 412

Using the Localization Wizard...................................................................................... 414

Accessibility....................................................................................................... 418
Designing Accessible Applications.................................................................................... 419

Introduction.................................................................................................................... 419

What Is an Accessible Application?.............................................................................. 420

Accessibility Guidelines................................................................................................. 422

Pega Accessibility Features........................................................................................... 423

Accessibility Compliance Guidelines........................................................................... 425

Accessibility Report........................................................................................................ 428

Example 1: Designing Accessible Layouts and Controls........................................... 429

Example 2: Designing Accessible Grids....................................................................... 432

Extending UI..................................................................................................... 434

Extending the Capability of the Skin................................................................................. 454

Building Dashboard Widgets............................................................................................. 446

Introduction.................................................................................................................... 446

Creating Widgets............................................................................................................ 447

Widget Configuration Options..................................................................................... 450

Creating Templates....................................................................................................... 452

Creating Purpose Specific Controls................................................................................... 435

UX Methodology............................................................................................... 463
DCO and UX......................................................................................................................... 464

Introduction.................................................................................................................... 464

Align UX Activities to DCO Activities............................................................................ 465

UI Prototyping for Pega Applications.......................................................................... 467

UX Strategy Best Practices............................................................................................ 468

Methodology and UX.......................................................................................................... 469

UX and Agile Methodologies........................................................................................ 469

Agile UI Design............................................................................................................... 470

Agile UX and Scrum....................................................................................................... 471

Avoiding Pitfalls with Agile Methodologies................................................................. 473

 Module 02: Getting Started

This lesson group includes the following lessons:

 What Is Good UI?

 Presentation vs. Content
 Dissecting UI

1
 What Makes a Good UI

Modern web technology has come a long way to achieve device-agnostic interface design. This
responsive design is critical to a great user experience.

At the end of this lesson, you should be able to:

 Describe the history of responsive web design

 Describe components of user experience
 Understand principles of great user experience

2
A Brief History of Responsive Web Design

3
What Is User Experience
User experience (UX) has graduated from being a hot trend to being a business staple, with companies of
all sizes calling on UX professionals to create more intuitive and engaging experiences for the users of
their applications. The User Experience Professional’s Association broadly defines user experience as:

Every aspect of the user’s interaction with a product, service, or company that make up the user’s
perceptions of the whole. User experience design as a discipline is concerned with all the
elements that together make up that interface, including layout, visual design, text, brand, sound,
and interaction. UX works to coordinate these elements to allow for the best possible interaction
by users.

Such coordination relies on the following skills and expertise:

 Understanding user sets (user research and usability testing)

 Planning the layout of information and the flow of a service (information architecture)
 Designing the way that users progress from one step to another (interaction design)
 Planning and writing copy and media content (content strategy & development)
 Designing the interface or overall visual system (visual design)
 The ability to pull all of these elements together with a cohesive vision (strategist)

From: vitamintalent.com

4
People tend to associate UX with a company’s digital experiences, such as websites or mobile
applications, but UX covers a much broader spectrum than what is online. Consider a bank. Banks offer
traditional “customer experiences” such as how customers interact with tellers at a branch or the process
of finding out a balance over the phone. Banks also have websites where customers can engage in self-
service activities such as checking their balances, transferring funds, or changing their mailing addresses.
Banks may have mobile apps where customers can deposit checks, ATMs where customers can get cash
and “back-room” applications through which loans are processed. Additional business lines within the
bank (such as investment banking) may have their own independent digital products.

From: vitamintalent.com

The UX team has to make sure that not only is the website is easy to navigate, the mobile app and ATM
are also easy to use. In addition, the back-room applications facilitate an efficient, accurate, and
productive environment, and that all the components look cohesive and provide comprehensive services.

Great businesses are built on great customer experience and great employee experience. The
businesses success with any application/web site is contingent on whether the end-user can succeed in
their tasks and whether their experience is positive. An end-user’s success requires user-centric, context-
sensitive designs which provide clarity to the user and ensure a simple and understandable experience.

A great user experience is all encompassing and ensures that end-users have positive and productive
interactions with the system. It is a combination of interface and interaction design, along with consistent
styles to reinforce familiarity and navigational standards. As a result, the goals, needs and wants of the
end-user should always be a priority.

As in any well-designed product, a great user experience is a combination of functional beauty and the
attention to detail. There is plenty of good design that is ugly, and of course there’s good design that both
works well and looks pretty. But a design that doesn’t work can never be substantially good - ugly and
broken is just worthless, and pretty and broken is phony or kitschy.

5
Principles of Great User Experience
Let us spend a few minutes and learn about the principles we should follow to create a great user
experience.

1. Bring clarity – The primary job of any UI is to bring clarity to the end-user. The end-user must
understand how the screen is intended to be used and how they can interact with it.
Understanding how users are going to interact with our application is the most critical factor in
providing a great user experience. We can achieve clarity by:

a. Enabling users to quickly identify important fields, buttons, navigation elements, and
regions of the screen.
b. Grouping similar or related data elements within a single layout so users clearly
understand how the information is organized.
c. Creating a visual hierarchy of the content/data. Important information is higher on the
screen and/or displayed in larger text.

d. Avoiding cluttering input fields with less important information, ambiguous icons, and
confusing labels.
e. Eliminating extra clicks/taps or needless confusing or convoluted interactions.

f. Avoiding overly long data-entry forms. Split them into multiple screens and use other
methods such as headers to simplify and clarify the information for the user.
2. Respect context – Clarity can only be achieved if we understand the correct context of the user
and what he/she is trying to achieve on the screen. By context of the user we mean:
o The user’s role
o Their previous experience
o Where they are now in the process
o The device they are using
o Their native language
Designs should be flushed out and simple prototypes built before any real development is done.
Remember to validate the designs with respect to context.

For instance, even simply printing out the design on paper and then attaching the paper to a
smart phone can shed light on whether the context of using the application on a mobile device is
understood. If a user can quickly find important elements on your paper prototype, you’ve
successfully tested your design with respect to the context of the device.

Review the user interfaces periodically with the end-users of all kinds. Developers often resist
change especially when their existing system is old but highlighting deficits in usability can drive
innovation. Providing data regarding the success of user adoption of the application — within the
context of role, experience, device, native language, drives interest in continuously improving the
application.

3. Be consistent - Users expect consistency in applications. Consistency is critical for our users to
create a “mental map”— the map we create in our minds when using any application or website
helps us to navigate and complete tasks. Notice when we use something as simple as a word-
processing program how we naturally return to the same areas on the screen to save work or add
notes. There are two primary aspects of consistency to consider:
a. Consistency in interaction patterns — such as where to look for menus, save/submit
buttons or the type of controls used for similar selection actions. Knowing when to use

6
 each control and using them consistently in our applications is critical for our user
success. Radio buttons should generally be used if we have seven or fewer choices,
otherwise a dropdown menu should be used, and an autocomplete should be used if the
selection list contains hundreds of options. Boolean values should usually be presented
as a single checkbox.
b. Consistency in styling — using the same color pattern, layout styles, button sizes,
fonts, and so on.
4. Keep the user in control – the user wants to quickly understand how to complete a task and to
feel in control of their experience. Make sure:
a. The user can recognize fields instead of having to memorize their location.
b. To use appropriate controls for the data to be entered. For example, use of a date-picker
for the date field, or a currency control if currency is to be input.
c. To use appropriate data types for the property to restrict users from entering invalid data,
when selecting integer, date, true false (Boolean) and so on.
d. To format the user entered values to specific formats such as a social security number
(SSN) or telephone numbers using edit validate or edit input rules.
5. Simplify - the user experience is critical to modern application building. The days of intensely
dense screens for business applications are gone. Our goal is to provide the optimal amount of
information to the user, according to their context. Look at how well-known applications such as
Linkedin change the amount of information on the screen when going from a desktop to a mobile
phone.

Additionally, we should simplify the number of controls such as styles, containers, and layouts..
Pega 7 contains a large repository of controls, an infinite variety of layout types, and the ability to
style anything in any way, but we should understand the purpose of this flexibility is to provide a
useful palette to all customers, not to complicate the UIs we build. Think carefully about using
more than what is required.
6. Provide an obvious primary action – Understand the primary action our users typically will
want to complete, and then ensure it is well highlighted in our UI. For instance if the screen we
are building is an approval screen, a large orange button with “Approve” would provide users with
an obvious primary action to take. Placing the “Approve” action in a dropdown menu where it is
hidden would be a bad decision.
7. Guide the user — Similar to providing primary actions, we should generally guide our users to
complete their tasks efficiently (understanding the user’s context here is key). Guiding the user
can sometimes be about structuring data on the screen in a logical way (important information at
the top or in larger type, and less important information below or in smaller type), or it can mean
providing a truly guided interface such as a wizard (“screen flow”). Guidance can also be added
by offering contextual help such as instructional text, judicious use of icons and other methods.
We do not recommend focusing on hover-tips which show instruction text via hovering over labels
and fields. Hovering is an extra task for the user who often has to go back and re-hover to
remember what the hover-tip said, and additionally hovering is not useful for users who cannot
use a mouse, as well as all users on touch mobile devices.

In all cases always be aware of the context of the user. Does a user new to the system need
more guidance than a user with more experience? Will an experienced user find a wizard
interface tedious and slow? Validating the design and the UI is critical.

7
 Content and Presentation

Introduction
A web application, or any web page for that matter, consists of content and presentation. Content is the
information provided by the application or webpage, and presentation is the way it is presented to the
user. With presentation and content separated from each other, developing and maintaining web
interfaces becomes more efficient.

At the end of this lesson, you should be able to:

 Understand the advantages of separating content from the presentation

 Articulate web UI techniques to achieve this separation

8
Separating Presentation and Content

9
Web Front End Code Basics
A web application, or any web page for that matter, is made up of content and presentation. Content is
the information provided by the application or webpage, and presentation is the way it is presented to the
user. In addition, there are behaviors that provide added interactivity and context awareness to the
application. For example, consider a very basic address capture form. The content in this example
would be the fields such as Street name, City, State and Zip Code. The presentation could be made up
of the font use, the placement of the labels, the background color etc. Filling in the City and State
automatically when the user enters the zip code would be the behavior.

In terms of web technology content is the HTML, presentation is the Cascading Style Sheet (CSS) and
behavior is a combination of JavaScript and some CSS. In this lesson, we will focus on content and
presentation. Behaviors will be discussed later in the course.

Content can live without presentation. Your application or web page will continue to provide the same
information regardless of the presentation. Content is defined in HTML using specific tags. These
structured tags phrase or group elements that provide semantic meaning to that content. For example
the <em> … </em> tags denote emphasis. When presentation is applied, <em> may mean bold text. But
what is bold text to a blind user? This is where the content and the way that content is presented is
important. The <em> is also treated as emphasis by the machine. So your browser emphasizes the
content and a screen reader tells the listener that the content is emphasized. Presentation is what gives
a sighted user visual clarity and form.

This is what The New York Times website looks like without any presentation:

10
And here is what it looks like when presentation is added.

The content can be completely understood without any presentation applied. But presentation provides
the visual appeal and design to the website.

Let us take a very simple example:

When the above HTML is rendered on a browser (Chrome in this case), it looks as follows:

11
If you notice, there is no Presentation applied to this webpage. There is no CSS. Yet, you notice that the
phrase ‘Hello world’ looks much larger than the rest of the text. This is because of the <h1> tags. <h1>
tells the browser that this is the first level of heading, and the Chrome browser renders it as shown above.
Every browser has a default CSS. For Chrome, the default browser CSS for <h1> is as follows:

Any additional presentation (CSS) is applied on top of this browser default CSS. So if you specify the
following CSS for my Hello world webpage:

The resulting page appears as follows:

Regardless of this change, or the default browser CSS, the content has not changed, and a screen
reader tells the user that Hello world is a first level heading conveying the semantic meaning of that
content.

12
The CSS Box Model
As mentioned earlier, the presentation layer provides visual styling to the content. A huge part of that
visual styling is achieved through proper spacing, demarking using borders etc., thereby providing visual
clarity of content or groups of content. The CSS box model provides the tools that allow you to create
that visual clarity. In the CSS box model:

 Each element (regardless how small or large) is a box

 Layout is created by putting rectangular boxes together
 Default width is the maximum width that fits into the parent element
 Default height is the minimum height that can fit in all the children elements
This is what the box model looks like:

It is made up of:

 Margin – Clears an area around the border. The margin does not have a background color and is
completely transparent
 Border – A border that goes around the padding and content. The border provides a colored area
around the padding and the content and its color is affected by the background color of the box.
 Padding – Adds space around the content. The padding is affected by the background color of
the box
 Content – The content of the box, where the text and images appear
 Total element width = width + left padding + right padding + left border + right border + left margin
+ right margin
In our Hello world example, we can apply the following styling to <body>:

13
The browser will render the following:

If we look at how the box model was applied:

The orange area is the 1em margin around the entire box. The black border can be seen around the
content. The green area is the padding around the content (body in this case), and the blue area is the
content.

CSS Layouts
There are two main layout types in CSS: inline and block. HTML tags inherently exhibit one of these two
layout types.

• Inline elements share a line on the webpage. Tags such as <em>, <strong>, <input>, <select>,
<img> are inline elements

• Block elements take the entire line for themselves. Tags such as <p>, <ul>, <ol>, <li>, <h1>
through <h6> are block elements.

• The display css attribute can be used to enforce a layout type.

CSS Typography: Fonts

A font is a displayable or printable text character in a specific style and size. The font is declared
using the ‘font-family’ declaration in CSS. Example of font families are Times, Courier, Helvetica
etc. There is also a generic-family such as serif, sans-serif, cursive, etc. In CSS the font-family is
typically declared by first declaring the font and then the generic family. For example, Times New
Roman, serif.

14
Applying one of three CSS properties can further enhance a font family declaration: font-style,
text-transform, and text-decoration. For example, font-style: italic, text-transform: uppercase,
text-decoration: underline.

You can also apply a font-size that determines how large the font is. Font-size is specified in one
of many units. In print, text points (pt) is the widely used, however in digital text pixels (px) and
ems are more commonly used. 1 em is the size of the font’s ‘em’ box (a square box in which
each font glyph is designed). The standard unit to get uniform typography is using em.

15
 Dissecting the UI

Introduction
The business success of any application is primarily contingent on whether end-users can succeed in the
tasks that we want them to achieve, and ultimately whether their experience is positive.

In this lesson we will look at some web sites as examples to see how the interface is designed to capture
the business goals. We will also compare the different design considerations in the context of desktop
and mobile interfaces.

At the end of this lesson, you should be able to:

 Discern the business rationale behind a particular interface design

 Understand the reason why a web site has a different design for desktop and mobile versions

16
Desktop Web UI Examples
To ensure that end-users can succeed in the tasks that we want them to achieve, through a positive
experience, is critical to the business success of an application. In order for us to create a good user
experience, we need to be aware of the business value we are trying to capture so that we can
understand how end-user’s interactions can help us to achieve our objectives.

The New York Times

Let us look at the online version of the New York Times as an example. The web site provides users with
a quick view of the world news and promotes its unique in-depth analysis of important political and
cultural happenings. At a high level the interface is divided into a top header bar and the main body
below, a form familiar to newspaper readers.

The header is further divided into three main sub sections: a wide branding bar in the middle, and two
thinner bars for searching and navigation on the top and bottom. The advertisement pictures on either
end of the branding bar provide quick links to revenue-generating subscriptions.

The navigation is designed in such a way that users can reach a news story within three mouse clicks,
either via the navigation menu bar or the Sections dropdown menu at the upper-left corner. For example,
to view the city’s cultural events, users can click on the Sections menu, hover over the New York menu
item, and then click on the Events sub menu item.

17
Below the header, in the main body, the content displays in three columns. The primary column contains
the summary and links to the most recent, in-depth, and news-worthy articles, the other two columns
contain news and editorials placed according to their categories. The column alignment, marked by the
dotted red lines (below), provides users with a visual queue for scanning. Note also in the secondary
column on the left, typography variations of the news titles indicate the importance ranking of these
headline stories.

Overall, the interface is presented with a top-down, center-periphery pattern that facilitates news-reading.

18
Amazon.com
Now let us take a look at the Amazon.com website and we will see a different UI pattern that supports
selling consumer products.

The site is designed to enable users to find products of interest and make buying decisions quickly. In the
header section, the shopping cart icon is placed in a floating section that can adjust automatically to the
screen size, so that the information is always available to users and they can see the current status of
their shopping. This dynamic arrangement eliminates the need for horizontal scrolling, and at any moment
during the shopping process, users are just one click away from checking out.

19
On the home page, the most popular items display in repeating lists according to product categories. A
list expands or shrinks itself depending on the screen size, and users can explore the list items within the
list container by clicking on the arrow at the end of the list.

Being another source of revenue for Amazon, the sponsored advertisements stay on the screen, floating
to the right, just as we saw with the shopping cart icon.

Once a search is performed and a product is identified, critical information is presented to support a quick
buying decision. A large product photo, price, discount, customer rating, availability for free shipping, as
any of these can be a deciding factor for users. If more in-depth information is needed for research, it is a
click away or a quick scroll down.

20
In addition to the product in focus, the site quietly suggests related items to encourage users to extend
their shopping experience. The reason, of course, is to increase revenue potential for Amazon. The
information provided for the related items is a higher level summary of the deciding factors discussed
above, presented in a more succinct form. Also note that the items are displayed in a repeating list,
efficiently maximizing screen real estate.

We can see that the Amazon.com site takes care to facilitate a users’ search and research on products.
Everything is designed to quickly fill up the shopping cart and move on to checkout.

21
In the next section, we will also review the mobile version of this site and compare the different things we
need to consider when designing desktop and mobile interfaces.

22
Mobile vs. Desktop Design

Conclusion
The goal of the user experience is to enable user interaction with the software to capture business value.

In this lesson we reviewed the web sites of The New York Times and Amazon.com to see how an
interface is designed to capture the business objectives. We also discussed how the design
considerations are different in the context of the desktop interface and the mobile interface.

23
 Module 03: Pega 7 UI Basics

This lesson group includes the following lessons:

 UI Elements in A Pega Application

 UI Architecture

24
 UI Elements in a Pega Application

Instruction
Pega 7 comes with a wealth of UI artifacts to build modern applications. We will discuss how these
components correspond to industry standard web technology, and become familiar with some important
Pega UI terminologies.

At the end of this lesson, you should be able to:

 Recognize Pega UI artifacts that are equivalent to industry standard web components
 Understand high level structure of the Pega UI

25
Pega UI Structure in Building Screens
Pega 7 comes with a wealth of UI artifacts to build modern applications. In the previous lesson we
explored the Amazon website. Let us look at it again, but this time let us see how the interface can be
constructed using Pega UI elements, and let us become familiar with the Pega UI terminology.

Portal
Anyone can browse products on the Amazon.com website, but once logged in, users has access to more
content, such as their account information and their order records, as shown below. An authenticated
user has a different view than an unauthenticated user.

In Pega applications, this concept of different views for different users is implemented as portals. A portal
is associated with an access group, all users belong to at least one access group. Users belonging to
different groups have access to different views and functions via different portals. For example, a
customer representative of an insurance company when logs in will be able to process accident claims on
their portal, while their manager can view the quarterly summary reports on claim processing on his
portal.

Harness, Section
Below is a screenshot of the search result for Toy Story toys. At a high level the interface contains three
large parts: the header on the top, the filtering criteria using categories on the left, and the search result
displaying on the rest of the screen.

The different parts of the screen all have their equivalents in Pega applications. In Pega terms, the outer
red box is a harness - the top level page that users see, and the inner green boxes are sections – the
building blocks of a UI screen. A section defines the appearance and content of one portion of a form - it
determines what users see and what they can do with the content.

Layout
Inside the search result display area, each product item takes a rectangular box and these boxes are
placed one after another to fill the display area.

26
In Pega applications, this arrangement can be achieved with a repeating layout. A layout organizes UI
elements within a section, it provides a structural skeleton for UI content.

The new dynamic layouts available in Pega 7 are DIV-based HTML elements. They are flexible to adjust
for varying display screens, thus have an important role in separating presentation from content.

Controls
If we take a closer look at the product items, we see that inside each rectangular box, sub elements are
organized and rendered in a similar fashion. A thumb nail image of the toy, a clickable text line for the
product name, price information, and customer ratings.

These sub elements are implemented in Pega applications as UI controls. The green box corresponds to
an image control, and the red boxes correspond to link controls.

Controls determine how data, text, images, and other information bits appear on user forms, for both
display and user input. Each of them has a unique look and provides different functions for users.

27
Skins
Skins help in controlling the presentation layer of the application. Going back to our New York Times
example, the content we see is defined in the section rule.

The same page looks like this when presentation is added.

As we learned in the previous lesson we use CSS to present the content better. Skins help in creating the
CSS using a simple user friendly interface without needing the expertise to write CSS. Skins help in
setting typography, applying the CSS box model, setting the style elements for all user interface elements
used in the application.

28
Pega UI Structure in Building Forms
Forms are rendered inside a user portal, so we will be essentially using all the same UI elements we
discussed in the previous part. From a case processing point of view, Pega UI’s are built with three main
UI elements: the Harness, the Section, and the Layout. Let us look at each of them to see how they are
used in building a Pega UI. Controls are useful in presenting data elements and we will learn also learn
about other UI rules as we progress through the course.

Harness
The Harness is the top level page that users view while creating, updating, or resolving business cases.

There are four standard types of harnesses that are shipped in the product to use in forms, and they are
tightly integrated with case management.

 New Harness is for collecting information before creating a case.

 Perform Harness is for executing process steps on a case.
 Review Harness is for viewing the case in read-only mode.
 Confirm Harness is for presenting confirmation that a case has been resolved.

Section
Sections are the building blocks of an application UI. A section defines the appearance and content of
one portion of a form, it determines what the user sees.

Work information and functionality are grouped into sections by context and purpose. Each section can
be included in other sections so that the developer can reuse them in a variety of contexts.

29
Layout
A layout organizes UI elements within a section. It determines how the information is arranged.

Layouts can only be included in sections. A section must include at least one layout to contain the data
elements.

There are several layout types supported in Pega 7 – the dynamic layout is one of the newest.

Dynamic layouts are based on HTML DIV sections, which are similar to tables, but faster, more flexible
and easier to use. Since Dynamic layouts are flexible to adjust for varying display screens they have an
important role in separating presentation from content.

Smart and Free-Form layouts are supported in the product for backward compatibility but have been
superseded by Dynamic layouts.

Repeating layouts and Column layouts provide more advanced layout features.

Dynamic layouts can adapt to the changing display area automatically. This feature, known as
“Responsiveness”, is required to render the application correctly for different media forms such as tablets
and smart phones.

Conclusion
In this lesson, we reviewed the well-known Amazon.com web site and mapped its structures and
components to the Pega UI technology, to familiarize ourselves with important Pega UI terminology.

In this lesson, we touched on some of the Pega UI components (Portal, Harness, Section, Layout, Skin,
and Control). We will learn about these components in more detail as we progress through the course.

30
 Pega UI Architecture

Introduction
In this lesson we will explore the Pega UI architecture at a high level and discuss some unique features of
Pega UI.

At the end of this lesson, you should be able to:

 Understand the Pega UI architecture

 Explain how the UI is generated
 Articulate the characteristics of the Pega UI

31
Pega UI Architecture
Pega User Interfaces primarily serve two purposes:

1. As a portal that controls and displays the workspace for the user when they log into the system.
2. As a form to gather information enabling users to create, update and resolve cases.

Pega UI ranges from the entire user portal down to individual content items such as text, buttons, and
other display controls. Let us look at all the UI rules, including those that are not grouped in the user
interface category. We have reviewed some of them in the previous lesson as well.

Portal Rule
The Portal rule does not hold any visual elements such as other UI rules. The main purpose of a portal
rule is to set up a work space for the user. All users have a primary portal assigned to them. Portal
references harness for content and skin for presentation.

Harness Rule
A harness is at the top level and it provides the framework of a UI screen. It represents the outer frame of
the work object form inside a portal. A harness references sections to build its content. A harness is used
in both screens and forms.

Flow Action Rule

A Flow Action rule controls how users interact with work object forms to complete their assignments. It
can be thought of as a place holder for a specific action that users can take while processing a case.

Technically Flow Actions belong to the Process category, but Flow Actions are important when building
the UI because they provide UI content to the users by referencing sections.

Section Rule
A section defines the appearance and content of a portion of a form; it determines what the user sees.
Sections are the building blocks of an application UI. They are referenced by other UI rules – harnesses,
flow actions, and other sections, for example – to deliver the content of and interface.

Skin Rule
Skin rules are used to define the styling elements used in an application, such as color schemes, font
schemes, and images to name a few. The skin rule does not require knowledge of CSS (Cascading Style
Sheets) and other styling elements to create them.

Control Rule
Controls are used to configure the presentation of data elements, for example, whether it should be a text
box, dropdown, radio button or checkbox. Pega 7 comes with a list of standard controls for all the most
commonly used presentation choices.

Paragraph Rule
Paragraphs are used to present static content in applications. Paragraphs use a Rich Text Editor and can
also reference data elements to embed dynamic data inside the static content. Paragraphs are useful
only to present data in read-only format for users to act upon.

Navigation Rule
Navigation is a special kind of UI rule whose primary use is to create a hierarchical data structure that can
be used when displaying content menus. The menus used in portal rules that come with the product use
navigation rule.

32
Binary File Rules
These rules are part of the technical category, however we use this rule type to store images in .png,
.bmp, .tif or other formats. We will create binary file rules to hold images as part of this course when
working on exercises.

Text File Rules

These rules are also part of the technical category, and we can use this rule type to store text files with
the extension of .css or .js. These are useful if we are creating any custom css or javascript to be used in
our application.

33
UI Stream Generation
UI rules are saved like other rules - they are applied to a class and are saved in a ruleset version,
enabling us to take advantage of the rule resolution, rule specialization and reusability as with all other
Pega rules.

When a harness or section is saved the system performs the following tasks

1. Saves the rule and in case of harnesses it also saves all the included sections.
2. Validates the Meta data by invoking multiple rule-utility-functions which can be viewed by using
the view xml link in the Actions menu.

3. Invokes a series of rule-utility functions to generate the code

4. Compiles the metadata including the layout data to Java classes, the Actions menu has links to
show the generated java file.
5. Saves the generated class file to the database and at runtime execution the html response is sent
to the browser. The HTML code rendered also includes the CSS and java scripts.

34
What Makes Pega UI Different
In this section we will discuss some key characteristics of the Pega UI – what makes it different and what
makes it successful.

Intent-Driven
A tremendous feature of the Pega UI is the use of Intent Driven Processing. Instead of presenting data
indiscriminately on a screen and letting users decide what data they need to complete their tasks, the
Pega UI guides users down an efficient and streamlined path to task completion.

Intent Driven Processing captures the know-how of the users, and uses best practices to drive live
customer interactions. It is all about providing the right functionality at the right time to the right people.

Model-Driven
In Pega application development, business objectives are captured as business processes and the UI
components are generated automatically based on the business process we are modeling.

There is a tight coupling between the user interface and the business process. The process determines
which user interface is rendered and the UI records are accessed only from within the process and not
from outside the process.

As a result of this mode driven approach, the UI can be built more quickly; the UI is contextually sensitive
to the type of business process we are modeling; and it can respond rapidly to changes in business rules.
In short this is “Build for Change®” at the UI layer.

Auto-Generated
Pega 7 user interaces are completely auto generated. We can build a user interface by dragging and
dropping fields or controls into sections and harnesses. The system generates the HTML code
automatically and we do not need to be proficient in scripting, styling or knowing HTML tags for creating
UI.

In Pega 7 the UI rules generate HTML5 and CSS3 code, thus produce good looking UI’s that can be
supported in various browsers such as Chrome, Safari, Firefox and IE. This also allows us to build the
interface once and deploy it in various presentation options such as desktop, tablet or smart phone.

Auto generation is a powerful concept. An auto generated UI empowers development teams with quicker
development cycles, less training, less maintenance of resources and an easier upgrade to higher
versions.

In summary, Pega UI is a robust and flexible tool that showcases how effective an intent-driven method of
processing work and completing tasks can be while providing users with a pleasurable user experience.

35
 Module 04: UI Building Blocks

This lesson group includes the following lessons:

 Creating the First Form

 Modifying the Display of Fields
 Rearranging Fields in the Form
 Styling the Appearance of the Form

36
 Creating the First Form

Introduction
User Interface rules in Pega 7 are primarily used for creating forms. These forms are presented to end
users for them to enter or review the information.

At the end of this lesson, you should be able to:

 Quickly build screens from the Case Designer

 Add fields to the screen
 Explore the rules created by the system

37
Demo: Creating the Form with Simple Fields
Now that we have seen the basics of Pega 7 UI, let us switch gears to see how to build a new form. We
are in the Designer Studio, looking at the Case Designer. The application that we are currently looking at
has a single case named Trip. It has three stages - Collect, Book and Ticket.

Each step listed under the stages is a specific action that is either performed by a user or is a sequence
of actions specified in a flow rule. To add a form to the first step, let us click on a step.

Notice that the right pane changes and now it displays the options that are applicable for that step. To
add a form, click the Configure Form button that is on the right pane.

This opens a new dialog for us to enter the list of fields that we want to see in the form. Since this step is
about Collecting Trip Details, let us enter the place, from which the trip starts, the origin,

and then enter another field for the destination.

Now that we have entered these two fields, let’s take a look at how it displays in runtime. To do this, we
click Submit to save the changes we made.

Then we need to open the Run menu and click the Create Case option.

There we go, the system created a screen with those two fields that we entered in the form builder, and it
also displays text boxes for the two fields we added.

Let us go back to the Case Designer and add few more fields.

Click the Configure Form button again to open the form builder.

Notice those two fields that we added earlier, now appears on the left pane. The fields defined using the
Form Builder is available in the left pane for all forms that we will add further on in this application.

Now let’s add another field. Let’s add a start date for the trip.

By default, the system assigns text to all fields but we do have the ability to change to a different format.
In this case let’s change it to pick Date. Notice it also has several other choices and we will look at them
individually as we learn to build more forms.

Let’s add one more field and select that as date as well.

Just to add a different flavor, let’s add comments field and select Text (multiple lines)

We can change the data type for the fields before we click Submit. However, once they are added the
system does not let us modify the data type. For the two fields that we added before, origin and
destination this selection is disabled. It is critical to decide the data type of the field before we click
Submit.

Let us test them again.

We can use the same case that we created earlier.

To see the changes we need to refresh the form, which is available from the Other Actions menu.

The system generated the form and the new fields that are created use controls for selecting the date and
for entering multiple lines of text. The fields appear in the order we added them in the Form Builder.

38
Exploring the Rules Created
As we saw in the demo, we can create forms very quickly within a few minutes. As we make entries in the
Case Designer, the system automatically creates all the rules. Let us take a look at the list of rules it
creates.

It creates a section rule which is the main rule in terms of what displays to the user. Looking at the rule it
actually is a representation of the runtime view in design mode.

The section contains the Dynamic Layout, which helps in aligning or grouping these fields. Each field that
displays here requires creation of properties which is another rule type and is part of the data model
category.

39
If we open a property rule, we can see that the system sets the data type and the associated control
based on our selection in the Form Builder. For example, this is how the origin property looks.

40
This is how the start date and the comments properties look.

Although the Form Builder looks easy, it is extremely powerful and we can use it to create UI forms and
fields that appear on them for the entire application.

41
 Modifying the Display of Fields

Introduction
The forms created in the application display a set of fields. Through these forms we either collect inputs
from the end user or present the values of those fields to users. In both cases, the presentation of the
value usually requires some formatting before we can present it to our users.

Control rules are useful in controlling the presentation of the values stored in the property and also
provide the appropriate input fields for users to enter information.

At the end of this lesson, you should be able to:

• Define and learn the significance of using controls

• Learn about the different controls shipped in the product

• Modify the control for a field created using Form Builder

42
Significance of Controls
Controls play a critical role in application development and their primary purpose is to:

 Control the display and presentation of properties(fields) at run time and

 Control the data entry by enforcing users to enter valid data
User interface screens displays fields for the users and we use controls to decide how they are displayed
in runtime. User Interface screens can present user input fields in three different ways:
1. As an input field – for the user to enter or select values
2. As an output field – to present stored values for users
3. As an input/output fields – to present stored values, and enable users to change it

Below is an example form:

Looking at the screen above we can identify various controls that are used:

1. Text boxes for entering Name & Email fields

2. Dropdown lists so users can select from a choice for the Where did you hear about us field.
3. Radio buttons for users to select the preferred email format field
4. Check boxes for the type of emails the users can subscribe to

There are other controls in addition to these.

1. Buttons for performing a specific action

2. Labels for each field that appears to the left of the field

43
As we can see from the form, controls are helpful for both the primary purposes we discussed earlier.
The controls decide how the fields display such as a textbox, radio buttons, checkbox or dropdown. If we
have requirements where we want users to enter valid data, we use controls such as dropdown, radio
button or checkbox to list various values from which they can choose.

We also saw the button control which is primarily used to perform a specific action. In this case, clicking
the green button allows users to subscribe and all values entered in form are saved, whereas clicking the
red button allows the user to not elect to subscribe any.

Controls can be classified into three broad categories:

1. Those that are used for collecting user inputs (User Input Controls)
2. Those that are actionable (Action Controls)
3. Those that present values in read only format

User Input Controls: Examples include text box, text area, date picker, etc. This also has another sub
category called list based controls. Examples include dropdown, radio buttons, etc.

Action Controls: Examples include buttons, links and icons.

Read-Only Controls: Let us defer this topic for now and will pick on this in one of the later lessons.

There are four main areas which we need to configure. We will learn about them in detail later, but for
now let us become familiar with them.

1. Basics – Here we configure the presentation mode (text input or radio button), the value
(stored value, another field, constant text, translated string, and so on).
2. Options – This is applicable only for user input controls especially the ones that require
users to enter values such as the date picker or the text box. Here we select things such as
size, style, placeholder, tooltips, and how buttons appear. For List based controls, the
Options change to Source options, where we configure how the list is populated.
3. Format – This decides the type of data that the user input field allows such as text or email.

4. Behavior - Action controls require us to configure behavior. In the example above, it allows
us to subscribe if the user clicks the first button and if the user clicks the second button,
their action is cancelled.

Control is a user interface rule which is auto-generated giving us flexibility to use in various browsers,
easier configuration options (eliminating the need to write JSP, JavaScript, CSS or HTML tags).

44
Standard Controls
Control is one rule where we will use the shipped rules as-is without any customization, but control does
allow us some configuration choices that make them look different. For example, we will not create a new
control for the green button and or the red button, instead we will use the standard button control shipped
in the product and then change the format of the button so that they appear in different colors.

This makes it imperative for us to become familiar with the entire list of standard controls that are shipped
in the product. Pega has upgraded controls to use auto-generated controls in the past few releases,
however all the non-auto generated controls that are used in earlier versions of Pega are still in the
system for backward compatibility.

The Designer Studio helps UI designers by providing the list of the most commonly used controls in the
palette. When designers work on the sections they see these two palettes (Basic and Advanced).

The Basic palette provides the list of the most commonly used controls such as text box, dropdown,
button, and so on.

45
The Advanced palette provides access to the list of advanced controls. We will learn more about them as
we build additional forms.

There are few other controls that we may use in addition to the ones that are presented in palettes but in
most cases, these two palettes list all the standard controls that we need to use in our applications.

46
Assigning Controls to a Field
When we use Form Builder to create a form, the system automatically assigns controls for the fields used
in the form. Remember that we must select the type of data before we select Submit. In this case, we
choose Text, Date, Email and dropdown.

Clicking the Submit button creates these fields as property rules,

47
and when we look at the property rule form for these fields we see the system also created a text
property, uses a textbox control in the rule form, and assigns the appropriate control.

If we open the date field, we can see the system creates a date property and uses the date control.

The system assigns controls based on the selection made in the Form Builder. For example, if we look at
the dropdown field it creates a text property, however it assigns the dropdown control and also stores the
values entered in the Form Builder in the property rule.

48
Similarly the email field that we entered in the Form Builder gets created as a property rule with email as
the control.

In the section where these fields are used, the system reads from the property rule form and applies the
correct control.

49
It is extremely helpful when the system assigns control in the property rule because the property may be
used in several forms and by defining the control in the property rule we can ensure that the same control
is used in all of our forms. This seem logical, however as we all know there may be cases where we need
to use a different control than what the system assigns.

For example, assume we want the Reason for Trip field to use radio buttons since there are only two
choices.

To support this functionality, Pega 7 allows us to modify the control assigned to the field in two places –
one being on the property rule form and other being on the section. Modifying the property rule ensures
the same control is used everywhere, while modifying it in the actual section offers additional flexibility.

To modify the control in the section, click the cell containing the dropdown to see the icon to view the
properties panel.

Clicking the icon opens the dialog for us to change the control.

50
Previously, we briefly looked at the basic and advanced palettes, it is important to know that they play a
key role in adding newer fields to a cell. We can add a control directly from the palette by clicking on the
name and dragging and dropping it on a cell. When adding a control directly in the cell, we need to
identify the associated property for that field. We will use this more when we build advanced forms.

51
 Rearranging Fields in the Form

Introduction
The Form Builder allows us to enter all fields that appear on the form and then displays them all in a
single layout. This is pretty useful to start with, however in reality the forms require much more than a
single layout.

At the end of this lesson, you should be able to:

 Add dynamic layouts in the form

 Embed dynamic layouts inside another
 Save layouts as sections to reuse them across other forms
 Set headers and sub headers on layouts to group them

52
Adding New Layouts
Before learning about how to add layouts, let us take a step back to review what we use layouts for. A
layout is a structure that is used in arranging the fields how we want them to appear on the form. The
arrangement decides the number of fields that we can see in a single row, the placement of the label,
width and height of the cell, and so on.

We know that the Form Builder creates all the forms using one standard layout format. We also learned
about changing this format if required. How will we decide if we want some fields to be arranged
differently? This is where we need additional layouts. Adding layouts is straightforward, in the section we
click the Layout tab, select layout, drag and drop it inside the section.

The important part is deciding where to drop it. As we learned earlier, sections must have at least one
layout inside it, so we have an existing layout. We should drop the new layout either above or below the
existing layout, the system displays an orange line indicating where the layout can be placed.

53
Next, we select the layout type, the default is the Dynamic Layout.

The layout it appears in the default format, which we can change if we want.

54
The second way to create a layout is to click on an existing layout and then use the copy option in the
context menu. The context menu can be accessed by using the right-click. After clicking the copy, we can
right-click again to see the Paste Above and Paste Below options.

Alternately we can copy by clicking the icon in the section.

We can also delete an existing layout either using the delete icon or by using the delete in the context
menu accessed from the right-click.

55
Embed Layouts
Layouts also allow nesting, to create one we drag and drop inside the layout below or above the cell
where we want to add it.

Nesting is an extremely useful concept when creating complex user interfaces and is supported only in
Pega 7. Below is an example of a form which is created using nesting.

In this example, we can see that the last row has three fields while the other rows have only one field. Let
us take a look at how this looks at design time, when we look at the section we see that it uses a layout
embedded inside another. Notice the layouts can use a different format.

56
Let us switch to another example to see how nesting helps to create sleek user interfaces. Below is the
Case Information tab on the case that appears by default.

Let us now look at the section that renders the part highlighted above. There are four layouts used to
render this screen.

57
Set Headers
As we build forms with various layouts, it is useful if we organize the forms using headers. Headers are
extremely useful in providing information about the fields that are in a specific layout. For example, this
form uses three layouts and each header provides information about that part of the section or layout.

Headers can be added in various levels, let us see how we can apply it on a layout.

58
The header settings appear after enabling the Display header and title field. In the Container settings
section, we can enter the text that appears as the header and also the header type. In the image above
there are three different layouts, the Pega Pulse section has a collapsible arrow which is set in the header
type field. If using collapsible layouts, we can set it to expand on load so that it appears expanded by
default otherwise it appears collapsible every time the form refreshes. If we are not using this setting, the
expansion occurs when the condition is satisfied or the user manually expands it by clicking the arrow
next to it.

The header can also include an icon along with the text. Enabling the Include icon with the title field
displays additional fields to select the icon source. We can also reference a property or Field value to
render dynamic or localized text.

59
Save as Sections
The scope of the layout that we defined applies only to this section rule which in turn means only to this
form at runtime. When building applications, we may also think of using a similar set of fields across
various forms. For example, the contact information that we created earlier might be required in additional
forms. To reuse this layout across several forms we need to save them as sections.

When we click the layout, we have the option to save as a section. Clicking this opens the rule dialog for
us and we could modify the names if we want to.

Saving layouts as separate sections allows us to build user interfaces quickly by deciding where to use
them and how to use them. Let us see how we can add a section inside the layout. We use the layout
palette, click the section in it and drag and drop it inside the section.

Similar to layouts, sections can be added either above or below another layout and can also be nested
inside another layout. This is an example where sections are placed inside a layout. Here the dynamic
layout is using the Inline grid double format and each cell in turn references a section.

60
Sections can be placed directly outside the layout as well, in which case the section uses the default
layout style to align that section.

Conclusion
This is the final lesson that concludes the UI Building blocks. We learned about building forms using the
Form Builder and assigning default controls in the Form Builder. We looked at the list of rules created by
the system and most importantly we looked at sections and ways to work on them directly. In the section
rules, we learned about applying other controls, changing the formats of layouts and controls to meet the
business requirements. In the last lesson on this lesson group we learned about applying headers, adding
additional layouts, including sections to create complex user interfaces.

Starting with next lesson group, the lessons take a single concept and go in depth and for this we require
thorough knowledge on all these concepts learned in this lesson group, please review this lesson group
once again if you need to do so.

61
 Styling the Appearance of the Forms

Introduction
Even though the Form Builder creates the form for us with all input fields in them, we still need to
configure the presentation of the fields at runtime. To keep things simple, the system uses a standard
layout template and the standard configuration choices for the controls used by the fields in the form. This
helps us to create the forms quickly and efficiently, we may need to work on these forms to ensure they
meet our specific requirements.

At the end of this lesson, you should be able to:

 Controlling the appearance of fields in a layout

 Configuring input controls for presentation and other options

 Specifying format on a button to distinguish from other buttons

62
Configuring the Presentation of the Form Layout
When we open the section rule that is created by the Form Builder, we notice that the system creates a
dynamic layout and all the fields inside it.

As we can see, there is a text here which says Action area next to the dynamic layout.

To change the format or presentation of the layout, we click on the actual layout.

Then we click the first icon that appears on the right. This opens the properties panel for the layout.

There it is, the Action area in the layout format field.

To change the format, we can use the first dropdown which shows a list of choices and other for
additional choices.

Let us select one from this list, we will pick Inline.

Then click Submit to apply the changes. The section refreshes to display the new layout format.

All the fields now appear in one row in this new format. But, this seems cluttered. Let us see what other
choices are available.

Let us select Inline grid double and see how this it looks now.

This format displays two fields in one row. Let us take a quick look at the additional choices.

Selecting Other displays an additional field where we have to select the format.

We see the additional formats available including the Action area that was originally selected.

Let us go with Inline with labels left and this puts all fields in one row. However with labels on the left, this
puts one of these fields in the next row.

How will this look at runtime? Let us see by saving the section.

Let us test them by looking at the case that we created earlier. Let us open the Recents explorer and pick
one that we worked earlier.

Notice that at run time the fields are wrapped to fit the width, adjusting the width automatically moves
fields.

We have made changes directly in the section rule instead of using Form Builder. Doing this restricts us
from using form builder for this form. If we go back to the Case Designer, we can see that the configure
form button is disabled.

63
Configuring the presentation of date controls
We can also modify how the controls that appear on a form display. This date field looks really bigger
than is needed.

To fix this we have to open the properties panel for the field.

The form builder by default uses the control that is defined as part of the property.

The Presentation tab works fine if we want to accept all the default choices, but the presentation tab
provides very little flexibility.

Using the Change button, we can pick the Date time control.

When we navigate to the Presentation tab it shows additional choices.

The size can be adjusted by selecting Custom.

The width can be configured either in % or px scale.

We can also configure the type of data that can be entered or selected.

The display mode field by default shows a text box with a calendar entry, the other option being dropdown
lists for year, month and date.

We can also restrict how the user enters a date. We can allow them to either enter the date in text box or
set it so that must always use the calendar control.

When selecting dropdown it changes some of the choices down below

The number of years field is interesting — it picks a range from current date. By default its set to 21 which
means it goes 10 years back or 10 years forward.

Let’s save this setting to see how it looks at runtime.

We can pick the month in the first dropdown, the day in the second dropdown and if we look at the third
dropdown we will see that we can pick a year between 2005 and 2025.

64
Configuring the Presentation of Other Input Controls Used in the
Form
After seeing the video for date fields, let’s take a peek at the form again, we see text boxes and a text
area. Let’s see what configuration choices are available for these controls.

The first step is to ensure that the control is selected in the cell referenced in the section rule and it does
not use the “Inherited from property” option.

The following table gives us the list of choices for other input controls and is a handy reference.

Control Size Data Type Specific to the

control
Text Selecting Custom will allow to Select Email, Min/Max chars
Input set width can be entered in % or Number, Phone, Text Alignment(Left,
px Text, URL center or right)
Text area Selecting Custom for both width None Min/Max chars
and height. Width can be Scrollbar
entered in number of columns,
% or px while height can be
entered in number of rows or px

Though the system gives us the ability to configure all controls which makes it flexible when we are
building user interfaces, we should not predominantly use it as a mechanism to adjust the presentation.

It is not a good practice to set controls on each field because it adds lot of overhead. In the video that we
saw earlier on the layout formats, we saw that selecting a different format adjusted the width of these
fields. It is important to use the appropriate layout formats to avoid changing control formats (specifically
to set sizes). However it is acceptable to make some of the format changes such as removing scrollbar on
text area or setting the orientation of the radio button choices on one or more fields. If more fields require
a similar setting then we should look for other alternatives which we will learn about when we build
advanced forms.

65
Configuring the Presentation of Buttons Used in the Form
Buttons are controls that are most commonly used for enabling users to perform a specific action. When
working on forms, it usually displays two buttons; the Cancel button and the Submit button. As the name
suggests, Cancel provides an option for us to cancel out of the form without saving changes while Submit
indicates that the user has completed all fields and wants to Save their work and proceed further.

Both these buttons look similar except for the background color. The Submit button looks more prominent
since that is the primary action we expect users to click on this form.

Let us open the section that is rendering the display of these buttons to see how these are configured.
Remember we are looking at an example of the standard button that is used by the system and we are
not going to change, however we are looking at it as a reference to modify the presentation of the button
whenever we need to.

66
We open the properties panel for the button and move to the presentation tab to see the format. The
Control formats used for Cancel and Submit are Simple and Strong respectively.

The preset format choices that are available for modifying the layouts and controls are extremely useful in
extending the forms generated by the form builder to meet differing requirements. By using different
formats, we can easily alter the presentation of the forms.

67
 Module 05: Designing Forms

This lesson group includes the following lessons:

 Creating (Advanced) Forms

 Sourcing List Based Controls
 Displaying Lists
 Displaying Hierarchical Data
 Using Layout Groups
 Displaying Read Only Form
 Displaying Static Content
 Displaying Contextual Help
 UI Toolkit

68
 Creating (Advanced) Forms

Introduction
Now that we have learned all the basics that we need to know about user interfaces, let us start looking at
other capabilities of the product that helps us in building forms. In this lesson, we will add on to what we
already learned about form creation by adding layouts and applying formats. As we learned earlier, using
the Form Builder helps in creating various rules such as properties and sections quickly, however we
might need to make changes in the section to realign those fields into additional layouts, modify their
controls and so on. Building User Interfaces starts from the Form Builder and then the UI designers use
the section and the designer canvas to finish creating these forms.

At the end of this lesson, you should be able to:

• Using dynamic layouts in screens

• Build some complex UI layouts

• Including Sections inside a layout

69
Dynamic Layouts
A layout is a structure useful in organizing the data fields in a section. Dynamic layouts are useful in
building the forms that can be dynamically altered to suit different screen resolutions. Dynamic layouts
are DIV based rather than table based. This provides lot of flexibility when it comes to displaying them at
runtime. Layout despite providing structure for organizing the fields is easily adaptable to display in a
different structure without huge coding effort.

Pega 7 ships five dynamic layout formats which can be used to style the layouts. They are:

1. Default – The product uses Stacked as default, we can change it to use any other format
that we think will be more commonly used across the application
2. Stacked – the items are stacked on top of each other.

3. Inline – the items are placed from left to right until it fits the screen.

4. Inline grid double – creates a data grid with two items in each row.

5. Inline grid triple - creates a data grid with three items in each row.

70
Besides these formats, Pega 7 ships several other formats in the standard skin rule. These formats help
to create forms quicker and can be added by selecting Other in the properties panel of the layout.

We will learn more about the styling aspect later but as of this moment, note that we can use all
predefined formats when designing forms. We can also add more application specific formats in the skin
rule if required. W we will learn about application specific formats in the Presentation lesson group.

71
Column Layouts
Dynamic layouts are the most commonly used layout, however in some cases we might need to use
Column Layout. Column Layouts are predominantly used in section rules that are used in a Portal rule,
however they can be used in sections that are used as forms as well.

Column layouts split the work area into two or three columns- the main area displays the primary content
that is relevant for that form while the sidebars provide additional information. Smart and Free Form
Layout types are supported in the product for backward compatibility, but should not be used in Pega7
applications. We will learn about the Repeating layout when we learn about displaying lists and creating
grid layouts.

Similar to Dynamic layouts, the Column layouts are styled using formats that are defined in the skin. Pega
7 ships three different formats that we can use. If we are looking at a website such as Amazon.com, the
product we are looking for is presented in the main section while a second column displays actions such
as adding the item to the cart or wish list.

72
Including Layouts and Sections
Layouts can be added directly in sections from the layout palette. Layouts can be placed directly in the
section or inside an existing layout. Placing the layout inside an existing layout causes it to look like
nested layouts. We can nest layouts to build complex screens that require different alignment of fields.

Complex UI forms can be created predominantly using

1. Dynamic layouts – applying the formats

2. Column layouts
3. Nested Dynamic layouts
In addition to adding layouts from the layout palette, we can also embed other sections inside one
another. Embedding layouts is only supported in Pega7, while embedding sections has always been
supported in the product.

Adding sections is similar to adding layouts, we use the layout palette to pick the section, click and then
drag and drop where we want to add it. Similar to layouts, the sections can be included:

1. Below an existing layout

2. Above an existing layout
3. In a cell inside an existing layout

When including sections, we can either pick the name of the section directly or use a property reference.
Using a property reference helps when creating reusable forms wherein the name of the section is not
hardcoded and the same section can be used to embed different sections.

The Page context field can be used to switch the class on which the section is defined. The default
selection “Use current page context” provides access to include sections defined in the same class or in
one of the parent classes defined in its hierarchy.

We can use another context by selecting a different choice in the Page context field.

73
Let’s look at them in detail:

1. Use data page – Selecting this option requires us to choose a data page already defined.
This switches the Class field to use the class of the data page. This particular option is useful
if we need to display the contents of a data page directly embedded in a section. For
example, we have a data page displaying all transactions made on a credit card and for us to
display the content without copying the data page into the case, we embed the section
displaying data page results directly in the section.

2. Use clipboard page – If the data is stored as part of another clipboard page (any top level
page) outside the context of the case, then we need to reference the data using the
clipboard page name. For example, suppose we want to display information stored as part
of system pages that displays in the clipboard, then we use this option so that we can display
any of the User Pages other than the pyWorkPage besides any of the system pages.

74
 3. Use page defined by property – This setting is more commonly used, and is useful when
we want to display the information that is stored as part of the embedded page property.
When we define a page property we usually associate it with a data class. A page property in
turn can include several scalar properties, including a page property that accesses all those
properties. For example, suppose we have a page property named Traveler that points to
the Orga1-BookaTrip-Data-Traveler class and in that class we see properties such as
Address, city, Date of birth and so on.

To display these properties we can define a layout that references these properties as .Traveler.Address
or create the DisplayTravelerInfo section in the Orga1-BookaTrip-Data-Traveler class and use .Traveler to
reference that section. Alternatively, we could also use the clipboard page and reference .Traveler
directly. This is the default behavior of the system when the form is created using the Form Builder. In the
Fform Builder, if we choose a page property and its associated properties, the system uses a section
include to access the clipboard page as shown below.

That leads us to the question, when should we use each page context?

1. Typically we use data page when the data is used strictly as a reference and not saved as
part of the case.
2. We can use clipboard page when the data is used as a reference or gets updated, however it
is saved as part of the case (either all the data or just a reference).
3. Use the page defined by a property to read from the embedded page properties.

75
 Sourcing List-Based Controls

Introduction
List based controls are input controls that we can use in forms when we want users to select a value from
a list of choices. List based controls eliminate the need for additional validation since it ensures accuracy
by presenting users with a list of valid choices from which to select. For example, we have a list of states,
so users can select the state in which they live. Another example of showing a list is when we want users
to select a rank on a 5-point scale.

Pega 7 ships a wide variety of list based controls that are useful in presenting a list in different ways. As a
UI designer it is important to have an understanding of the capabilities, the limitations and how to
configure these controls. For the examples listed above, we will use a dropdown list for the user to select
a state and provide radio buttons for rating on a 5-point scale.

At the end of this lesson, you should be able to:

 List all of the standard list based controls shipped in the product
 Explain the various ways the list can be populated
 Use data pages for sourcing these controls
 Configure an autocomplete control
 Determine the appropriate control to use on a specific requirement

76
Standard List Based Controls
In this section we will learn about the following standard list based controls.

1. Drop-down control
2. Radio-button control
3. Autocomplete control

Drop Down Control

A drop-down control presents the list of choices in a select box and lets users select one from that list by
using the box. This is an example of the drop-down control.

Adding this is straight-forward, we can configure the property to use pxDropDown or we can directly add
a drop-down control from the basic palette if the property requires us to use a different control in another
form.

77
Like other controls, the drop-down control offers several configuration choices. The attribute that is
specific for a drop-down is the ability to include a placeholder. If a placeholder is not included, the drop-
down selects the first choice when it’s rendered in the form.

Radio Button Control

The radio button control presents the list of choices that users can select in a set of radio buttons. This
can be added similar to how we can add a drop-down control. It includes the ability to indicate ‘Not
Available’ as a choice if required.

78
Radio button controls require some specific presentation choices in the properties panel of the field. We
can select the orientation of the radio button to display the list of choices either vertically or horizontally.

At run time the options look like

The other key choice in orientation is to specify how many radio button choices can appear in a column or
row (depending on its orientation). Setting this in turn wraps determines how the text is presented to the
user either to the right or below.

79
At runtime the presentation will look like:

Autocomplete Control
The autocomplete control presents the list of choices in a user selectable format where the values appear
as and when the user types a few characters of it.

Autocomplete offers several configuration choices and we will learn about them in detail in next part of
this lesson.

These three controls allow users to select one choice from a list of choices. If we want users to select
multiple values from a list, Pega 7 supports checkboxes. Checkbox and multi select boxes work with
repeating grids and we will learn more about them in the Displaying Lists lesson.

80
Sourcing List Based Controls
List based controls should display a set of valid choices from which users can select or pick. This list can
either be static or dynamic. For example a static list can be the list of months in a calendar year. A
dynamic list can be a list of active accounts for a particular user or a list of product categories that the
company is selling.

The choice of sources depends on whether the control is displaying a static or a dynamic list. Let us take
a brief look at the various choices that can be used as sources for populating the list. All the list based
controls that we saw earlier (dropdown, radio button or autocomplete) can use any of these sources to
display a list of options.

1. As defined on property — The list of choices that are stored as part of the property rule.
This option is most useful when presenting static lists. The other three choices are usually
used when working with dynamic lists.
2. Data Page — These are objects created in memory to provide the list of choices that the
application can use. Data pages can pull data from various sources, can contain logic to
periodically refresh the data and can improve the application performance. We will look at
them in detail in a little bit.
3. Clipboard Page — These are pages that exist in memory while the case is being worked on.
Clipboard pages are usually populated by the rules written by developers for processing the
case. Though the structure is similar to data pages, the clipboard page does not offer
benefits such as automatic periodic refresh, sharing data across several users or keeping the
data available for the entire session.

4. Report Definition — This is a rule type written to query results directly from a database.
Report definitions can query from Pega specific data tables or any external database table
and internally it generates SQL statements to execute the query.

For choices 2, 3 and 4 the data that displays at runtime are stored in page lists. A property saved as a
page list is a data structure consisting of an ordered list of pages, each identified by an integer index
(starting with 1). A page list property similar to an embedded page property requires identifying the class
structure and defining a page list which in turn creates a page list with one or more pages belonging to
that class. All properties that are saved as part of that class are also embedded in the data structure.
Page lists are a Pega 7 representation of the array data structure.

81
Populating Static Lists
When the list source is set to use “As defined on property” it uses the configuration choices set in the
property rule form. Setting the choice in the property rule form provides us the benefit of reusing it
wherever the property is used.

The choice of the sources is configured in the Table type field on the property rule form. (For more
information on the Class Key value and the Remote List review the Client side Validation lesson. To
display the list of instances we should not use the Class Key value or the Remote List. Instead we should
use data pages. So this lesson does discuss those two options. In addition to the Client-side Validation
lesson, refer to the Help menu if you need to use them in your application.)

In this section we are going to learn about:

 Local list
 Prompt list
 Field Value

Local List
The local list allows us to hardcode values as options that display at run time. We should use this if the
list of options is small, does not change often and the application does not have any localization
requirements. For example, the maximum number of tabs that the form can display. This property
pyMaxTabs are used by Pega to limit the number of tabs a user can open in the standard portals shipped
with the product.

82
Prompt List
This is an enhanced version of local list and must be used in lieu of local list, primarily because it supports
localization and it also supports key value pairs. The Prompt value can reference a field value rule which
supports localization. Again, this option is useful only for small lists. For example, suppose we have a
field named Fiscal month, where the users pick the month’s name (January, February, March) while the
system stores its key (1, 2, 3 respectively). The value entered in the Prompt value is what is displayed to
the user while the value entered in the Standard value is what the system stores internally. If we are
localizing the app, a French user sees as (janvier, février, mars) and system stores the key as 1, 2, 3
irrespective of the user’s locale.

Field Value
We use field value rules to populate the list of options. This is applicable if we have a scenario where the
list changes more often and requires periodic updates. This option is suited to display a fairly large list
since it involves creating a separate rule. Here again we use the state example but the field values can be
useful if we want to extend to states that belong to other countries.

83
The Field value is a rule belonging to data model category and it uses field name and localized value in
addition to the field value. If we go to the Records Explorer and search the Field Name (pyState), we see
all the field value rules defined for that field name.

Below we see how the field value rule definition looks. The rule is applied to the Data-Party Class, the
field name (pyState) and the actual field value rule name (CA). The rule form provides the option to enter
localized text.

Field values store only localized text and use the combination of Field name and Applies to Class to
locate the list of values. The field value can directly be referenced in other rules as well. We will learn
about them throughout this course. Refer to Translating the labels and messages lesson to understand
how the wizard can translate field values to a localized text.

84
Populating Dynamic Lists
There are three choices- Using a Report Definition, Clipboard Page or a Data Page to populate dynamic
lists. Of the three options, we recommend that Data page be used as much as possible. But before we
proceed, let us discuss the inherent advantages and limitations of each of them.

Using a Report Definition directly queries the results from the database table where they are stored.
This is useful when we need to get the latest data from the database table. One of the bigger drawbacks
in using the report definition is that it always queries the database which can be quite costly. Keep in mind
that querying database limits the number of concurrent users (due to the restriction in the max number of
connections that can connect to the database at one time) and there is a network delay, and a
performance impact in accessing database every time we need to populate the list.

The Clipboard Page option uses the clipboard page that is in the user session to display a list. This
works fine except it does not provide us the advantages of a data page. The clipboard page once
populated might become stale unless the application contains logic to refresh the list. The clipboard page
created is applicable only for that specific case and not accessible outside that scope. Clipboard pages
are also not shareable across multiple users.

Data Pages are a new feature in Pega 7 which simplifies the application development significantly. Data
pages allow the decoupling of data from the application. UI designers can now focus on designing the
interfaces without knowing how the data is being populated, whether the data is stale, which user has
access to viewing the data and so on. Data pages offer several advantages:

1. Data pages help in creating the separation between the data and presentation. The data
page definitions are separate from the user interface screens. Pega 7 UI rules are designed
in a way that the changes in the data page definition does not impact the user interfaces
using them.
2. Data pages define the data structure, refresh strategy (how frequent the data gets
refreshed), the scope of the data (is it stored in a specific case, is it accessible across all cases
in a specific user, is it accessible by all users logged in to a specific node) and source from
which the data page is being populated. These are usually designed by data modelers and
are available for user designers to use them.

3. Data pages when accessed for the first time, create the page in memory and on all
subsequent requests, the system uses the page created in memory thereby improving the
performance.

Since data pages take care of most of these issues, User Interfaces do not require any modification
unless the data structure of the data pages change significantly.

85
This example uses a data page to display the list of all positions for which the company is seeking
candidates. When the list based control uses this data page as a source it references the data page as its
source. Notice the list source option selects the data page name and the specific property in that data
page that is used for displaying the options.

Let us take a look at another data page usage, here the data page is also accepting a parameter. This
helps in reusability, so the section can be used for different possible values. In this example, the data
page was displaying a list of HR plans and depending on the type it shows the list of dental insurance
plans or the health care insurance plans that the company is offering.

As a rule of thumb, data pages should always be considered as a first choice rather than using the other
two Using report definitions are not required in most cases since data pages in turn can use the report
definition as its source. Using data pages sourced by report definition helps in improving the application
performance since the retrieved result can be reused as required. For example, if users can go back to
the same form that they submitted earlier, then using a report definition will query the database again
while the data page will use it from its stored state eliminating a database request.

Clipboard page options are useful to query from system pages such as the operator record, access
group, and other system pages that are in memory. Using them directly avoids the need to create a
custom data page rule to store the same result that is already in memory.

86
Configuring an Autocomplete Control
The Autocomplete control is useful if we want users to type in few characters to see the list of appropriate
choices. There are several configurations that are specific to autocomplete, and we will take a closer look
at them. We will skip the choices that are common to other list based controls since they work in the same
fashion. Let us look at some generic examples:

87
The first one lists all options that starts with the search character c, the second one lists all the options
that contains the search characters physic and the last one displays additional columns and uses one
column for search. Pega 7 provides the autocomplete control that is useful in presenting all the above
combo box examples without requiring the developers to write any complex jQuery or other custom
programming effort.

Autocomplete like other controls can use data pages. Here it uses a data page named D_OfficeList as its
source. This data page contains the list of offices the company has. Let us focus on some of the fields
that are specific to the autocomplete configuration.

Autocomplete requires a minimum of one property, so the first property (Office Name) by default is the
value associated with the selection and is also shown in the autocomplete control. We have the option to
add additional fields and must enable them if that property must be shown or should be included in
search.

The other important field to note is the “Match start of string,” which when enabled performs the “Starts
With” search as shown in the first example where the user is searching on the character c. If we disable
this option, then the system performs the “contains” search.

The Min search characters is another key field, this determines how many characters the user needs to
enter to see the list of options. Refer to the Online Help for additional configuration options.

88
Conclusion
List based controls offer the ability to present a list of choices from which users make a selection. How do
we decide which control to use? The following table presents the scenarios and provides guidance in
making your selection.

Control name Use cases

When the number of options does not exceed 10
Radio button When the options are Boolean (yes/no, true/false)
Rating scale (1 to 5, Good to Poor)

When the number of options does not exceed 30 or 40 items. Having a longer list
Dropdown requires quite a bit of scrolling impacting usability.

When the field needs to display a big list of items, using autocomplete helps in
Autocomplete narrowing the list by searching on the list.

89
 Displaying Lists

Introduction
List based controls are useful when you want to present a list of choices to users from which they can
make a selection.. When the list becomes multi-dimensional, it requires other options. In reality, lists can
be much more than just allowing users to select one item. For example, an account holder would like to
see the list of all pending transactions posted on his account, a manager would like to see the list of all
orders placed by his team over the past month, or a customer would like to see the list of all products sold
by the company.

The lists presented to them can be read-only as we saw in the examples above. Let us take a look at
some other examples. For example, a shareholder would like to create a list compromising various stock
options while building his portfolio, an employee would like to provide the list of all dependents, or a
shopper would like to add products to the shopping cart.

At the end of this lesson, you should be able to:

 Describe the various options to display lists

 Use different sourcing options to populate a grid
 Create different ways to edit the items in the grid
 Configure grids to display lists in a user-friendly format
 Filter the results of a grid
 Paging the results of a grid
 Understand when to use grids and when to use repeating dynamic layouts

90
Displaying Lists
Lists can be displayed as part of list based controls. But, what other options do we have instead of
presenting them in a list based control? Lists can be broken down into two categories:

1. Ordered lists – Each item inside a list is ordered sequentially, one after another. In Pega 7, the
data model to support this structure is known as page lists. Each item stored in the page list has
an index associated with it and is referenced as .Transaction (1), .Transaction (2), and so on.
2. Unordered lists – The items in this list do not follow any order. In Pega 7, the data model to
support this structure is known as page groups. Each item stored in the page group has a
subscript defined as part it and is referenced as .Phone (<Home>), .Phone (<Work>), and .Phone
(<Mobile>).

Lists can also be categorized as:

1. Single dimensional lists – These lists have only one property in it.
2. Multi-dimensional lists – These lists have several properties and are presented as a table of
rows and columns.
Multi-dimensional lists are usually presented in the form a grid (also known as spreadsheet) with rows
showing the number of items in the list and columns showing the various fields of the list.

In recent times, the data is now being presented in other modes either vertically or horizontally.

91
To support this functionality, Pega 7 uses two separate layouts. We have

1. Repeating grid layout – which is useful when presenting a data grid consisting of rows and
columns
2. Repeating dynamic layout – which is useful when presenting a dynamic layout styled with any
format (stacked, inline or inline grid double) in a repeating group

Grids can be added to sections using one of these ways:

 Form Builder — Use the form builder to include a page list, including the page list and the
properties you want to see in the grid.

 Layout Palette — Use the layout palette and select layout and drop it in an existing section either
above or below or inside an existing layout.

After dropping the layout we need to set the layout type and to select either of them we need to select
Repeating layout. Then in the dropdown that appears next to it, we can select either Grid or Repeating
Dynamic layout. (Note, the other choices, Tree Grid and Tree are discussed in the Displaying Hierarchical
lists lesson.) Column and Tabbed Repeats exist for backward compatibility and is not to be used in any
new applications built on Pega 7.

92
Sourcing Options for Lists
All the options that we used in list based controls can also be used to source the Grids and Repeating
Dynamic layouts.

If using the Layout Palette, then we need to select the source and add the properties manually.

When using form builder the source is set to page list automatically, but if we use data pages as the
source, then we need to manually add Grid Layouts from Layout Palette. Report definitions should
seldom be used as the source except when building virtual grids. When using virtual grids, the grid
automatically displays all the properties that are defined in the report definition. When a new property is
added to the report definition, the grid automatically displays them without us requiring adding them
manually.

93
When using virtual grids, the grid layout dynamically looks up not just to display the rows (results) of the
report definition but also the columns (fields) of the report definition rule.

When using repeating dynamic layouts, the source can be either page list or a data page.

When adding repeating dynamic layouts, the system allows referencing a section inside the repeating
dynamic layout. In this fashion the whole section gets repeated. The books shown in the image below is
an example of a repeating dynamic layout. Each book also lists several properties such as the title,
author, price and a button to add it to cart. The highlighted part in the image is the repeated part or the
item inside a page list.

94
If we look at the underlying section rule, we see that it uses a repeating dynamic layout sourced by a data
page and it uses an Inline format, so each item is displayed inline until it fits the width of the screen

Whereas, the section that is placed inside the repeating dynamic layout uses a stacked layout to present
the page list properties one below another.

95
Edit Modes of Grids
When using repeating dynamic layouts, we need to configure the section that is repeated individually.
This is similar to how we configure other sections. However, when using grids, there are few options we
should be familiar with.

Grids can be presented as read-only by selecting None in the Row editing field.

Inline and Master-Detail displays an editable grid. When selected inline, we can configure to have the
rows always appear editable

or have the rows display read-only and become editable once users click on that row.

Master-detail is used to display a detailed screen for the user to enter new rows. The content of the
master-detail screen is rendered through the use of a flow action. When electing the Master-detail as the
Row editing option it offers three choices for displaying details.

96
If we select the modal dialog, then the details appear in a modal dialog for users to enter values.
Expandable rows allow us to present the details of the row directly below it and it can be configured to
use an expand icon instead of the click action.

Embedded elsewhere usually works in a way that clicking a row displays the embedded details in a
different layout either below the grid or wherever it is added in the section.

97
Configuration of Grid Features

Demo: Sorting the Results

One of the more common configurations we will use on grids is the ability to sort the results.
This is an example grid with four columns, let us click on the company name field.
Notice it displays the sort icon pointing upwards, indicating that the grid is sorted on company name in
ascending order. If we click on the company name again, the results are sorted in descending order.
And, the icon now points downwards. We can sort of any of the four fields, if we click on price, the results
are sorted on the price field.
End users can change the sorting at runtime on any field and it always refreshes the list and indicates the
sorting field and the sorting order.
Let us now see how this is configured by the developer.
In the properties panel for the grid layout, sorting is configured as part of the Operations tab.
Sorting is enabled by default. We can disable it by unchecking the checkbox in this field.
Disabling sorting here disables sorting on the entire grid. There are some additional settings in columns.
To select a column we need to hover over the top of the header until we can see the tooltip “Click to elect
column”.
We then click on the cell containing the column to see the icon. Then we click the icon to open the
properties panel for the column.
Here we have the ability to disable an individual field. When we unselect the checkbox we disable sorting
only for this field.

Demo: Categorize the Results

In addition to sorting, grid results can also be categorized based on one more columns.
In this grid, we present the list of employees each of them categorized by their role and then by their
status (full or part time).
We can sort on any field that is part of the grid.
When sorting on the column, the system sorts by the category, so in this case the name is in descending
order inside each category.
Now that we have seen this demo, let us go back to see how this is configured.
The configuration is pretty simple. We enable the Categorize grid rows field in the properties panel of the
repeating grid layout. This is similar to sorting and we can see this on the Operations tab.
As the label suggests it also has some additional settings on column.
When we click the column and look at the properties panel,
it displays the option to enable the column to be used for categorizing the results
and the default order in which it sorts the results.

Demo: Filter the Results

Filtering offers us the ability to narrow down a search to a specific result from a long list of rows.
When enabled, we see a new icon next to the field, similar to sorting, filtering gets enabled on all fields.
Filtering works based on the data type. If we look at the filtering choices for a text value, we can choose a
value.
Alternately, we can also do a keyword search and the product searches for the values containing this
keyword.
Here we see choices based on the selected value if the searched keyword.
If we search on numeric values, we can choose the actual value or a range of values.

98
If we search on date values, again we can choose a range of dates or
we can use one of the shipped functions to make a selection based on current week., month, quarter and
so on.
Filtering is configured similar to the way we configured the other features we have seen so far. We open
the properties panel of the grid layout.
We then need to enable the “Allow Filtering” choice on the Grid Operations tab.
.Similar to sorting and categorizing, filtering also has additional settings on the column level.
Enabling the Display selected filter values first displays the selected filtering text at runtime for the end
user to see.
There are other choices on the Operations tab such as reordering, and show details. We recommend that
you use the Online Help to learn more about the other choices available to you.
Let us select a column and here we can see two choices for the filter operations.
The filtering field has four choices –
Auto indicates that the field allows searching both on the values and the range.
List Only limits the search to all values that are part of the property.
Range/Search includes the options to search based on the range of values and
None disables the filtering operation on that column.
The filter by field defaults to value and is the most commonly used.

Demo: Paging the Results

Sorting, categorization and filtering features help us narrow our search to a specific row when the number
of records is large. However, paging or pagination helps to present the data neatly. Without pagination
the UI form would need to display all the results in one page.
Pega 7 supports a wide variety of paging styles, the first one we see here presents records in pages. We
can navigate between pages using the arrows to go to the next page
or to the last page,
we can go back to the previous or first page similarly using the other arrows.
Alternatively, we can enter a page number to directly go to that page.
The second format we want to see is Rows 1-Y,
so here instead of pages the system groups the data based on the number of rows.
The third format we want to use is page numbers which is similar to the arrows, except it uses the
numbers or the text (previous, next) for navigation.
First X results format displays only the first few records based on the number entered. In this example we
see the first 5.
To see all the rows, we need to click the show all link.
The last one we want to see is progressive.
Progressive offers performance improvements by rendering only those results that are requested.
It does not display the icons or the text to navigate between pages, it renders all results on one page
however, it populates only the number of rows requested. To see additional records, we need to scroll
down and the system populates the results as and when we scroll.
Let us now see how we can configure the paging feature.
The Paging feature is enabled similar to other features on the Properties panel of the grid layout.
There are two fields that we need to configure for paging and they are on the General tab
The first one is the Pagination format, where we see the list of various choices we just saw in the demo,
and we can pick the one that best suits our need .

99
After selecting the format, we need to select the number of rows per page., Pega 7 provides a list of
commonly used values.
If we want a different number that is not in the list, we need to select other and we can enter the number
in the new field.
Grids allow sorting by default, but we need to enable and configure all the other features we discussed if
we want to leverage them.

Conclusion
Both Grid and Repeating dynamic layouts are auto generated, user friendly (added using drag and drop),
easier to maintain (no coding required), support responsiveness and is supported both on mobile and
offline.

Grids are useful when presenting the list of items in a spreadsheet (tabular) format with rows and
columns. Repeating dynamic layouts offers more flexibility and hence must be used in most cases where
we want to present a list.

Repeating dynamic layouts are recommended in all cases unless we require features such as paging,
filtering and sorting to be used. Repeating dynamic layouts is simpler to configure and provides all the
benefits.

100
 Displaying Hierarchical Data

Introduction
Listing repeating content can be displayed using grids or repeating dynamic layouts unless the repeating
data is hierarchical, meaning it has multiple levels of data and has nested relationships. We can see a
data model using these relationships in companies that sell products. For example, when we open the
Amazon website we see that they sell various products in electronics, books and amazon home services
to name a few amongst several other categories. When we drill down one level under books, we see
books, Kindle books, textbooks, magazines and so on. When we drill down inside Kindle books, we see
genres such as Children’s eBooks, History, Mystery, Comics and Graphic Novels, and so on.

How do we build a data model that supports such repeating hierarchical relationships and more
importantly how do we display them using auto generated user interfaces in Pega 7?

At the end of this lesson, you should be able to:

 Build the data model required to build a hierarchical relationship

 Use trees to present a hierarchical relationship of parent-child
 Display additional details of a node
 Use tree grids to present trees and grids in one output

101
Data Model for Hierarchical Relationship
Before looking at the data model, let us quickly look at some examples of the hierarchical relationships in
action.

The list of employees lists their direct reports under each employee name at the second level. Abigail
Lippman has two levels – The first level has Jake, Jeremy and Josh and Jeremy has Kate and Kurt
reporting to him.

However Gene Porter has only one level in the reporting structure which has Cheryl, Olivier and Priya.

The data model should be able to support 1-n levels as well as different nesting levels for different row
items.

We know that the product uses page list as a data structure for storing repeating lists. Page lists
correspond to a class name and when a new row is created, it can use all the properties defined in that
class. The example above listed a one-dimensional hierarchical data model.

If we use one page list to display a row of items, what do we need to display another row of items inside
the next level? That is right, we need another page list, for the above example this is the data model that
it uses.

102
Here we see that pyEmployeePL is repeated three times, if we look closely, it actually has pyEmployeePL
inside a data class, so it looks like it has repeated three times, but if we expand the third one it has one
more and it keeps repeating itself. This is one of the standard properties shipped in the product, so you
can check it in your Pega 7 environment. Looking at the property definition we see that it references the
same data class that it is being referenced in. By referencing the same class, we have created the data
model that can repeat itself any number of levels deep.

As we can see in the screenshots, this property also has other properties such as pyDateofBirth,
pyEmployeeID and hence can be used to present a multi-dimensional representation as well.

103
Using Trees
The layout that can present the example where we show the screenshot of all employees in a one
dimensional grid is known as Trees.

Trees support most of the other features supported by the grid layout. As we can see here, it allows us to
edit a specific employee and when clicked, displays the additional details for that employee. If we look at
the underlying rule, we see that it uses a tree layout which can be added from the Layout Palette.

104
Similar to grids, trees also offer an Operations tab which allows us to configure where the editing occurs.
In the example above we saw that clicking a row provides the details screen embedded in another layout.
One other point to note is that trees also support sorting, filtering and pagination features.

105
Using Tree Grids
A tree grid is a combination of a Tree and the Grid layout. It shows the hierarchical relationship we see in
a tree and each row in the tree grid can display additional columns like a Grid. In this example, it displays
additional details of the employee in the same row. This example uses the same data model that the tree
layout was using, so if we expand the nodes we see a similar structure. Notice the employee details of
the child node also displays in its row.

Let us now look at how the tree grid is configured in a section rule. This looks similar to the repeating grid
layout except its name is different.

The rows on the tree grid layout can be edited by double clicking on the row. Again sorting, filtering and
pagination are supported in this layout as well.

106
Conclusion
Tree grids can also reference a report definition as its source in addition to a page list. There is several
presentation options for both trees and tree grids in terms of the icon used to display next to each row,
the headers, message when there are no rows to display and so on. Since trees and tree grids use the
expand collapse feature to display the child level nodes, the expand pane edit mode is not supported.
Trees and Tree grids can also be edited in modal dialog. When using tree grids, sorting and filtering can
be applied on all columns.

107
 Using Layout Groups

Introduction
Responsive UI forms require using dynamic layouts in the application to render them correctly for different
screen resolution widths. A Layout group is a feature offered in the product that helps us to group
different dynamic layouts and render them in different formats for different devices.

At the end of this lesson, you should be able to:

 Explain the Concept of a Layout group

 Configure Layout group

108
Explain the Concept of a Layout Group
Layout group as the name implies groups several layouts and presents them together. A Layout group
can contain any number of Dynamic layouts, Column layouts, repeating Dynamic layouts, or other layout
groups. The Layout group allows you to specify the type of navigation a user will use to navigate sets of
information.

A Layout group is useful when displaying content that is related to each other and enables users to
navigate between the content. Prior to using Layout groups, the product supported adding tabs or
accordions directly into a layout, which renders the same as that of a Layout group. Despite the similar
look and feel using Layout group offers several advantages:

1. Seamless rendering of the layouts as compared to the older layout options

2. Better control in terms of achieving mobility because it supports tap and swipe seamlessly
3. Uses HTML5 document type achieving similar functionality in modern browsers
4. Complies with accessibility standards
5. Supports responsive behavior, automatic switching to different formats easily

We will learn more about mobility and responsiveness in the Mobility lesson group. Layout group lets you
present different layouts in various formats using the display type field, which we will learn about in detail
in the next part. It allows the ability to swipe for tabs and menus when accessed on a mobile device. A
header can optionally be added for the entire Layout group, however we need to set the header or title for
each layout embedded inside the Layout group since that displays to distinguish the layouts.

Layout groups allow nesting another layout group inside it. When embedding a Layout group, we can
also elect to defer the load of some of the content.

109
Configuring a Layout Group
To add a Layout group we use the layout palette in the section. Click the Layout group and then add it
similar to the way we added a layout. We drag the control and drop it anywhere in the section.

Then we need to select the way we want the layout groups to present different layouts in the section.
Adding the Layout group displays a dialog for us to select how the Layout groups should be presented.

After adding the Layout group, we can add other dynamic layouts or sections as part of the Layout group.
When using them the Layout group puts a default text named Title. We need to open the properties panel
of the layout or the section include changing the header title.

110
Layout groups can be configured to present the layouts in different ways:

1. Tabbed – To display them to appear as tabs. This is also the default format in the standard skin
shipped as part of Pega 7.

2. Accordion – To display them to appear in accordion. Accordions display layouts in collapsible

headers and we could view one of them at a time. Accordions take up less horizontal space than
tabs so they are the preferred format for tablets or other devices with lesser screen resolution.

111
 3. Stacked – To display them to appear as separate stacked layouts one below the other. This
again takes up less horizontal space, however unlike accordions they display all of them one
below other. This format makes them appear as a list.

4. Menu – To display a menu with the layouts appearing as options in the menu. Using the menu
control we can select which layout we want to see.

5. Other – Any custom formats that you would create if required. This is just a placeholder if custom
formats are created in the skin rule to have the layouts appear differently than the ones above.

To conclude, Layout groups are extremely useful in grouping several layouts and present them in
different header formats using tabs or accordions or one of the other supported formats.

112
 Displaying Read Only Form

Introduction
Forms should be able to present the data collected from users or the data received from a system in a
read-only format. This is extremely common when we have applications where we collect information
from a user and then present the summary of the information to give users an opportunity to review what
they entered.

At the end of this lesson, you should be able to:

 Reuse the same form for both display and edit modes

 Decide when to use which approach to create a read-only form

 Create Read-only forms that can appear on multiple stages of the case

113
Different Ways to Create Read-Only forms
Let us take a look at the various ways we can create a read-only form.

1. Different rules - We could create two separate rules (one to collect user inputs) and one to
present them in read-only format. This approach is not recommended since it involves
creating multiple rules (potentially duplicates). There are some cases where this might be a
good approach so we will look at this shortly.
2. When rules Control – We could build one section and then use when rules to control
whether the fields display as read-only or editable.
3. Privileges- This is another option and it involves using security roles.

Let us see look at each approach.

Creating Read-Only Sections

While adding fields into a form using the form builder we have the option to choose Read-Only for the
field. This should not be confused with the Calculated (read-only). The latter is used for fields which are
calculated using declare expressions (not collected through user inputs).

When we look at the section, we can see that the field is marked as Read-Only in the Edit options field.

Creating When Rules

The field as we can see in the above example is rendered Read-Only always. Instead we can configure
the field to use a when rule. If we look at the other choices in the Edit options field, we can see that we
can add a condition directly using the Read-only (expression) option or we can use Read-only (when rule)
and use a when rule to control when the field should be rendered as read-only.

114
Creating Privileges
Privilege is a security rule created in a Pega 7 application. Privileges are associated with Access roles
and typically these are defined in the system by Lead System Architects or Security experts. Let us learn
how we can associate these predefined privileges as part of the section. Unlike the other two options
privilege can be associated on the layout level and not on the field level. To apply a privilege we need to
save the entire layout as a separate section. This option is rarely used because of this restriction.

The big advantage on the third option is that it can make the entire layout read-only. The first two options
work pretty well except we might have to set all the fields in a form to be read-only. Let us see how we
can set the entire layout read-only.

115
Setting Forms as Read-Only
If we need to set all fields read-only on a single layout we need to save them as sections. Let us look at
two different scenarios to understand how we can set the entire section as read-only.

We saw that the read-only flag can be set on the field level. We could embed the section into a layout and
then set the entire layout as read-only. This renders the entire section as read-only, including the
embedded sections if any.

After including the section inside a layout, we can use the Presentation tab in the properties panel to
configure the Edit options. This allows us to use the first two approaches that we discussed previously.
The approach of setting the layout as read-only makes a lot of sense because by saving layout as a
separate section we can share the section between multiple flow actions. Just to reiterate the relationship,
each form that a user sees on the screen is associated with a flow action and the flow action is
associated in a case stage. For example, suppose we have a trip selection form where users select the
travel details, and then we want the users to review what they entered in a review trip form. To
accomplish this, we need to save the trip details as a section and then use it in both flow actions.

Let us now look at the second scenario. Assume that the trip details have to be presented at all stages of
the case since all steps would also involve looking up the trip details. If this is the case, the easy option is
to include the section in all flow actions used in the application. But thankfully, there is a better option
provided in Pega 7. To include the same section on all steps we need to include the section as part of the
perform harness which automatically renders the section as read-only. That is impressive considering we
need to include it in one place and not even worry about setting it in read-only mode.

116
When working on the harnesses, we can use the Live UI tool to see the sections that are included in the
perform harness, and we can update one of these sections to include this section. In the newer versions
of the product, the system generates a section named pyAutomaticallyGeneratedCaseDetails and it
contains the information the system thinks is logical to be included as part of all harnesses. It does allow
us to customize this section.

Conclusion
We have learned different ways to render read only forms in a Pega 7 application. Let us summarize each
option as shown in the table below.

Option Use To Present

Separate sections
When rules or Expressions
Privileges
Including section in a layout
Including section in a harness
Use this if the review form has to look considerably
different from the collection form. Be cautioned, that this
option is costly because we are creating duplicate
sections.
Use when we want to reuse same section for both read
only and editable formats and display the content as
read-only on all forms other than the one where it is
being collected from the user.
Use when we want the form to be presented as editable
for a specific set of users and read only for all other users.
Use when the layout is repeated in several forms and
there are too many fields.
Use when we want a specific layout to be repeated across
the entire application or several steps of case processing.

117
 Displaying Static Content

Introduction
Forms should be able to present static content (content that does not change) to users. At times the static
content may also include dynamic content that is stored in properties which is collected as part of case
processing. For example, when users order a product, the application must display a review order screen
which presents information such as terms and conditions of the order, return policy, shipping information,
contact information, FAQ’s which are common across all orders and it should also display the order ID
and maybe the item description.

At the end of this lesson, you should be able to:

 Present static content in ways supported in Pega 7

 Explain the need for enhancing the text output
 Decide when to use a Rich Text Editor (RTE)

 Decide when to use paragraphs

 Explain the limitations in using paragraphs and RTE’s

118
Presenting Static Content and the Need for Enhanced Text Output
Static content can be presented to users in multiple ways in Pega 7. Let us explore the different ways..
There are a couple of options in the basic palette such as Labels and Formatted Text Controls that can
be used to enter plain text.

1. Labels – Labels are added similar to controls in the section from the basic palette. As the
name suggests, it is usually added to reference a label for the field. Labels are useful in
presenting smaller texts in the section. There is no limitation to the number of characters
entered in the label. But, from a usability perspective it is not a best practice to enter a lot of
text in the text box that displays to the user to enter text.

In addition to entering the text directly in the Value field, we can also reference a field value
rule. Field value rules support localization wherein we can have localized labels based on the
user’s locale. We will learn more about field value rules in the Localization lesson group.

119
2. Formatted Text Control – Similar to labels, Formatted text offers more choices for the
sources of the text. This control is useful to display the property value or the display text
when the property has a list of options to from which to select.

The Constant option (shown above), allows developers to enter text directly in the property
panel though it does not give us the choice to enter localized text.

3. Controls marked as Read-Only

The text input and text area controls when marked as read-only can also be used to present
a Constant value. This works the same way as the Formatted Text control.

120
Static content in some cases requires special formatting such as marking some text in bold or including
images along with the static text or property values (dynamic content) along with the static text. Let us
look at the different ways we can do this.

1. Paragraph rules- There is a rule type in Pega 7 called paragraph rules which allows
developers entering text. Paragraph rule belong to the User Interface category. This is an
example of a paragraph rule. Paragraph rules support rich text editing capabilities and also
let us reference an image or property. We will learn more about this rule in the next part of
this lesson.

2. Rich Text Editor control – Pega 7 also ships a Rich Text Editor control which allows end
users to enter static content. As the name suggests, this control supports Rich Text Editing
features similar to paragraph rules. The Rich Text Editor works a little differently than
paragraph rules because it requires end users to enter content.

121
3. Mimic a Sentence format in dynamic layouts – The dynamic layout can use one of the
special formats shipped in the product named “Mimic a Sentence.” When added, this
displays fields in adjacent cells as though they are part of a sentence. Using this option we
could use the cells to contain the label, image control, another section, a paragraph rule or
other controls.

When we look in the section rule, we can see that it uses four cells to display this sentence –
Sort and on top are labels,

the second cell is a link which displays the text “newest”

and the last cell is a checkbox with the Show subcases as the caption.

As we can see mimic a sentence can work if we are generating a sentence containing static
and dynamic content. It is also easier to apply formatting on these individual fields using the
formats supported in the control rule.

122
Using Paragraphs
Paragraphs are useful if you want to render a paragraph of text which has mixed characters in terms of
static text, images, dynamic values populated by the property value and so on. The Paragraph rule also
enables us to create enhanced text by using the editor in the rule form. The editor provides various icons
that help us in creating rich formatted text using different font sizes, font types, bold/italicize, indent, use
bullets and so on. We can also embed images and tables and the paragraph rule also provides various
copy and paste options.

Paragraphs are also useful when rendering dynamic values by directly referencing properties or rules. We
can use these icons to directly reference a property or another rule respectively.

When inserting a property, we can also fill in the control (in the format field) and optionally include a when
rule. The property allows us to include any scalar property or an embedded page property.

123
Including a rule icon allows us to reference either a paragraph or a section rule inside the paragraph. The
Using Page allows us to reference the paragraph or section defined on an embedded page. Again we can
optionally specify a when rule.

Paragraph rules can be embedded inside another paragraph rule. Can you think of other places where a
paragraph can be invoked? Paragraph despite being a rule type is available to be added similar to a
control inside the section from the advanced palette.

Since Paragraph is a rule, it offers several advantages such as reusability, specialization, versioning and
inheritance. Some of the limitations in using a paragraph rule is that the localization wizard (which we will
look at in detail in the localization lesson group) does not automatically translate the text entered in the
paragraph rule. However this is the only way to include a formatted text paragraph with dynamic values.
For more information on the other options in the paragraph rule refer to the developer help.

124
Using Rich Text Editor
The Rich Text Editor (RTE) offers similar formatting controls to those offered in the paragraph rule. As we
have seen earlier, the RTE is presented as a user input for the users to enter values in them. Since it is
only available at runtime, users can only enter rich formatted text and cannot reference properties or
other rules. They can reference images and links inside the static text. The RTE control can be added
from the advanced palette into the cell. After it is added, the control needs to reference a property which
stores the values. Some of the options can be enabled or disabled in the properties panel.

At runtime, when users access this control it shows all the toolbar options, they can enter text inside this
control and use the toolbar to format the text and include a URL or image.

125
The RTE control when marked as read-only renders the content entered in the previous screen similar to
how a paragraph is rendered.

Conclusion
We have learned different ways to render static content in a Pega 7 application. Let us summarize with a
table listing when to use each option.

Option Use To Present

Labels and are useful for presenting smaller text. It also
Label supports the localization feature.
Read only values of the stored property values and can
Formatted Text and Other Controls display constant or static text.
Longer text in the form of one or more paragraphs that
Paragraph requires indentation, coloring, different font schemes,
dynamic content requiring accessing values from
properties or another section.
A field where users can enter static text that requires rich
Rich Text Editor text formatting.
A mix of static text and dynamic values stored as part of
Mimic a Sentence properties together in a single sentence. It also provides
support for formatting individual fields by supporting the
formats on the cell.

126
 Displaying Contextual Help

Introduction
When we are building forms that display fields that require users to provide inputs it may be essential to
provide information or guidance to the users for them to complete the form.

There are quite a few approaches we can follow, but it depends on the use case. So let us take a look at
the different ways we can present guided help while using auto generated user interfaces in Pega 7.

At the end of this lesson, you should be able to:

 Explain the need for contextual help and how to present it

 Use controls to provide contextual help
 Create smart tips to provide additional information
 Create smart info to provide additional information

127
Why Do We Need Contextual Help?
When designing forms, it is critical for designers to be cognizant about the various fields that appear in
the form, how they can arranged in a layout and how much space the fields occupy on the screen. While
displaying a form, we need to be aware that we cannot crowd too many fields on a screen thereby making
it difficult for users to complete the form.

Displaying help text directly on the screen takes up more space, thereby making it more difficult for users
to navigate. We can provide a button or an image asking users to click it if they need additional help.

When users click this icon we can open up another section detailing the relevant information in either a
popup window or in a modal dialog. But, will that be sufficient? It may work in some cases and may be
overkill if a user just wants to know more details about a specific field in which they are expected to enter
values.

When UI designers build forms, they first need to make sure they can make it easier for users by keeping
things simple thereby avoiding the need for contextual help. Pega 7 in fact helps designers to achieve
this. Let us explore the different choices that are available.

1. Using a different label: It is a common mistake made by developers to name properties using
the same name that they use in the backend system or in a database. Doing this makes it hard
for users if other applications in their company do not follow proper naming conventions. There
are many advantages in keeping the names consistent in your applications. Pega7 supports the
ability to use a different text for label than the name of the property. But, we need to ensure that
the label is named to what the field actually means thereby helping the users understand what
that field means.
2. Intent based UI: Pega 7 uses flow actions to present a form and when presenting a form, we can
provide a short description for the form that displays for the user. Using a description that
matches the list of fields presented in the form also helps users. If there are multiple parts to the
form, then we can use headers to group similar fields.
3. Training: This may not be feasible in some applications but for some internal applications or for
applications catering to a specific set, we can provide training sessions so users are aware of
how the application works.

It goes without saying that we need to try to adopt these strategies and other similar strategies to avoid
creating contextual help. Despite that we may still need to define contextual help and in this lesson we will
learn best practices for creating contextual help.

128
Using Controls

Tooltips
Tooltips are often used in websites to provide contextual help, and are being used by many HTML
developers. When users hover the mouse pointer over an item, without clicking the item, a tooltip
appears. Note that tooltips do not appear on mobile devices since there is no cursor or hover action thus
limiting its use.

So, how do we create tooltips? When a control is added to the cell, we can configure tooltips on the
properties panel.

The text entered in the tooltip field can reference a field value rule so in this case when we hover over the
text box at runtime; we see the following text which is defined as part of the field value rule. We will learn
more about field value rules in the localization lesson group.

Placeholders
Controls can also be used to add smaller text using placeholders. In this example where we have the
location field we are adding a place holder text.

129
At runtime, the placeholder appears by default when the screen loads.

It disappears when users enter values in the field.

Using a control, we also have the option to use an event based model to present a smart tip or smart info
using a control. Let us take a look at that now.

130
Using Smart Tip or Smart Info
Smart Tip is an improvised way to present tooltips, usually activated by hovering or clicking over a control
or an icon. This lesson does not cover how actions are associated with events, which we will learn in
detail in the Dynamic User Interface lesson.

All controls can be associated with an action set. An action set primarily has two parts – an event (for
example hover, click, etc.) and what should happen when the event occurs. Let us examine this by
attaching the event to a link or an icon control.

In the Actions tab of the control, click Add an event and then select any event to which we want to
associate with this smart tip.

After selecting the event, click Add an action and then click All Actions to see the Show smart tip option.

131
Once added the screen looks like this:

The smart tip has two parts – an optional header that can be referenced in the Header Source field, which
when enabled displays a header on top of the smart tip text. The second part is referenced as part of the
tip Source field.

The sources for both the header and Tip can be a message rule, a property, a field value or plain text. If
the application requires localization using a message or field value is essential.

The Format field lets us select the style format we want to use to present the smart tip text.

132
Smart Info
Similar to Smart tip, we can also use Smart Info, which when selected lets us see the information as
shown below. The content displayed as part of Smart Info is rendered from a section.

133
Styling Smart Tips and Smart Info and Using Action Controls
Let us take a look at how the Smart Tip and Smart Info display at run time.

The Smart Tip and Smart Info can be styled using the skin rule and we can also use the Format field to
select the specific format (style) configured in the skin rule.

In addition, to using smart tip or smart info an action control such as a link or button can be configured to
launch a flow action in a modal or an overlay dialog. The Overlay looks similar to the Smart info while
modal opens the section at the top of the existing screen. In rare cases we could also choose the
Replace current option.

When using flow actions to display help text, it does display the Submit and Cancel buttons expecting the
users to perform an action. However the system allows us to modify these button labels or even hide
them altogether in the Action tab of the flow action.

134
If we hide the action section buttons we should provide a button in the section to close or dismiss the
dialog. There is an action called Close shipped in the product for this purpose.

Conclusion
Let us conclude the lesson by looking at the different scenarios and when we would use ach control. This
list is provided as a guide for the UI designers to decide when to use each type of control. However, the
actual selection is dependent on the mockup or what the end users prefer.

Control name Use cases

Is useful to display tips for an individual field. Similar to most websites where the help
Tool tips appears when hovering over the field. Quite challenging when the UI is extended to
mobile devices. May require us to style labels differently to indicate a tooltip is added
for that field.

Good alternative for a tooltip and is engaging as well. The placeholder appears by
Placeholder default and does not require users to hover. It renders well on mobile devices as well.
The limitation is that the placeholder is limited to few characters and cannot have
longer text.

Useful to present longer text and it also can include an optional header. Supports
Smart Tip styling and is useful in most cases. It can be activated by multiple events (hover, click,
etc.) which makes it user interface friendly and support mobility.

Similar to Smart Tip except it uses a section so the help text can present a large
Smart Info section which can use multiple properties or even display an image to help users
filling in the form. Useful in cases where we present help text for the whole form
instead of one field.

Similar to Smart Info except it is useful in cases where we need to display the section
Action control in a modal or replace the content window.

Note: If we require custom content to be presented, we can use Smart Info or Action control to customize
the section that is being presented.

135
 UI Tools

Introduction
Pega provides a collection of tools and features, which enhance our productivity and expand our design
capabilities. In this lesson, we will examine and discuss how we can take advantage of the UI tools to
efficiently build a UI that meets all of our user experience requirements.

The UI tools include the following:

 User Interface landing page

 UI Gallery
 Live UI tool
 UI Kit ruleset
At the end of this lesson, you should be able to:

 Describe the tools and features available in Pega 7

 Know how to use the Live UI tool to view screen elements and make real time updates
 Explain the features and tools available on the User Interface landing page
 Use the UI Gallery to access and view features and functions in user interface examples, and to
reuse example components in our applications
 Define the UI Kit ruleset and know how to use it in our applications

 Describe other third-party tools we can use to facilitate our UI design efforts

136
Using the Live UI Tool
The Live UI tool helps us to identify Pega 7 UI elements rendered on screens. We can quickly make UI
adjustments to runtime presentations and publish or discard changes on the fly. Live UI enables
developers to quickly edit most properties, controls, or layouts without the technical expertise required to
manage individual rules in Designer Studio. For complex updates, we can also use the tool to navigate
directly to the rules.

A Quick Look at the Live UI tool

To review or edit the elements in a screen, click the Live UI button. We can position the button
anywhere on the screen for ease of use.

Activating the Live UI tool displays a sidebar column that contains three tabs. By default, the Tree tab
displays a fully expanded hierarchical list of all the elements on the current page.

137
Clicking any of the items collapses the list to show only the hierarchy specific to the selected element.

To select an element, we move our mouse pointer over any of the items on the page or in the sidebar,
which highlights the artifact in blue in both locations.

We click the item on the screen or the name on the sidebar list to change the highlighted element from
blue to green.

Selecting an item presents several icons next to the element’s name.

 The up arrow icon displays a breadcrumb trail panel with a list of immediate ancestors (sections
and harnesses only) in a hierarchical list.
 The magnifying glass icon opens the rule in Designer Studio.
 The gear icon opens the element’s cell properties panel.
 The info icon displays the names and properties in the properties panel
 The hamburger icon lets you (depending on the element) open the properties panel, add or delete
elements, or add properties to the Scratch Pad.
Declarative properties have the letter “D” displayed next to their names in both the sidebar:

138
And on the screen:

For more information about Live UI tool’s capabilities, see the PDN article Using the Live UI
tool http://pdn.pega.com/node/116126

Runtime Editing in the Live UI Tool

In addition to using Live UI to inspect elements in our screens, we can use the tool to update the UI
directly from the runtime screen enabling us to see how our updates will appear in real time. Runtime
editing allows us to:

 Update properties in UI elements

 Add, delete, and move UI elements

Enabling Runtime Editing

To enable runtime editing we must first create a branch ruleset designated for this feature. The branch
allows a lead developer to first review the checked-out copies of the edited rules, then check in the
approved updates to the branch, and finally merge the branch rules into the application ruleset.

To set up the branch, open the application and create a runtime branch and ruleset on the Current
development branches section. It must be the first branch in the application.

In our example, we have created a branch called RuntimeEdit which is a branch of the Purchase
application ruleset. Click the Actions menu and select Use for edit at runtime to enable the feature.

139
When we enable it, the Edit at runtime label appears next to the branch name.

Editing Element Properties

To update element properties, we click the gear icon on a selected element to open its property panel.

When we submit our updates, they are saved into a checked-out branch version of the rule. We can view
the updated rule in the Pending tab on the right panel.

To check in the rule to the branch version, we click the arrow next to the update name. If we want to
check in all the updated rules on the tab in one action, we can click the Publish all button.

To undo our most recent update, we can click the Undo icon on the header. We can also remove any
unpublished updates by clicking the x icon next to the name or by clicking the Discard all button to
remove all the items on the tab.

We can review the history of the items we have published on the History tab, which shows the date, time,
approver, and check-in note.

Adding, Moving, and Deleting Elements

Using the runtime editing feature we can add new UI elements before or after an existing element, move
UI elements within or across dynamic layouts, or delete elements.

140
Add Elements
To add an element, we click the Hamburger icon on a selected element to display a menu that lets us
choose where we want to position the new element on the existing layout.

When we select a position, a menu appears that lets us select the element we want to add. In the
example below we are adding a calendar control beneath the Price field.

When we click the item, the control appears on the screen.

141
Move Elements
To move elements within a Dynamic Layout, we select it in the Tree tab on the element panel and drag it
to its new position in the hierarchy.

Note: We cannot move UI elements within and across Dynamic Layouts but can move them across
sections.

Delete Elements
If we want to remove an element, we select it on the screen and click Delete in the Hamburger icon
menu.

Now let us view videos that demonstrate how we use runtime editing.

142
Live UI Editing

143
Adding, Moving, or Deleting UI Elements Using the UI Gallery
The UI Gallery provides working samples of effective and dynamic user interface configurations. The
forms and layouts represent best practice implementations and are guardrail compliant. We can easily
view the underlying rules and elements that were used to build the screens and copy them in our
applications and customize to suit our requirements.

To open the UI Gallery, click Designer Studio > User Interface > UI Gallery. There are two main areas:
Showcase and Available Components.

Exploring the Showcase Examples

The working examples in the Showcase area demonstrate fully developed, production-ready screens.
For example, click the Contact Form sample to see how dynamic layouts were used to build the form.
Explanatory text describes the various elements and how they work. We can enter or select values in the
fields to imitate the user experience.

View the Underlying Rules

We can explore the underlying rules that were used to build the screen by clicking the View design-time
configuration link at the top right corner of the screen. Here is the section in which the Contact Form was
built.

144
Alternatively, we can use the Live UI tool to view the hierarchy of elements, view the properties, and
access the rules.

Exploring the Available Components

The Available Components area is divided into four groups, each of which presents working examples of
screen elements and controls.

Components — Examples include controls such as autocomplete, button, and checkbox. Where
necessary, pre-populated data instances are included in the examples to demonstrate their functionality.

Layouts & Containers — Examples that include three types of dynamic layouts and layout group.

Tables & Grids — Examples include grid, tree, and tree grid

Samples & Combinations — Examples demonstrate complete features that are commonly used in
screens. Some of samples demonstrate how combinations of individual functions can be used to build the
sample. For example, the Build a List sample shows how we can meet the design objective by either
clicking a row in a grid or using autocomplete.

145
Reusing Rules and Elements
We can quickly and easily incorporate the samples by opening the underlying rules and copying them into
our application ruleset, which we can then customize. This approach eliminates the need to duplicate the
functionality by manually rebuilding it.

Note: Some of the examples are in final rules. Remember to change the rule availability from Final to
Available in the copy.

Navigating the UI Gallery

While working with UI examples, we can navigate among the items on the UI Gallery page by clicking the
Navigate menu. Click an item to open it.

We can use the links at the bottom of the menu to return to the UI Gallery or to open the skin used by the
gallery to view or customize it.

While viewing an example, we can use the links in the See Also panel to open examples that are related
to or are used in the current example. For example, the Compose Email Form example contains links to
other examples that highlight specific rich text editor functionality.

146
The Recently Visited menu on the UI Gallery header lets us quickly open examples we have viewed.

We can use the search box on the header to select examples.

To close the UI Gallery, we click the Close button located on the header.

147
Using the User Interface Landing Page
The User Interface landing page provides us with a set of tools and features that help improve our
productivity and design capabilities. The landing page includes the following items:

 UI Gallery
 Skins & Portals
 Image Library
 HTML5 Application Readiness tool

 Localization tools
Let us take a look at each of them.

UI Gallery
Provides working samples of effective and dynamic user interface configurations. The forms and layouts
represent best practice implementations and are guardrail compliant. We can examine the underlying
rules that are used to build the sample, which we can leverage by copying them into our own applications.

Skins & Portals

The Skins tab helps us locate the available skin rules in the system. Double-click a skin name to open the
skin.

The Portals tab shows the portals in use by the current and built-on applications, their associated skins,
and the access groups and operators that use them. Click a skin or portal to open it.

148
Image Library
Helps locate images saved as binary file rules in the current application, plus those in base rulesets. Each
.GIF or .JPG, .PNG image appears along with its name and the relative path. To search for an image,
enter any portion of a file name in the Search Images box. Below is an example of a search on the text
“sample.” Select an image and click the Open Rule button to open its binary file.

See the help topic Image Library landing page for more
information. https://pdn.pega.com/sites/pdn.pega.com/files/help_v717/basics/v6portal/landingpages/useri
nterface/galleries.htm

HTML5 Application Readiness Tool

Helps us upgrade pre-Pega 7 applications to render in the HTML5 Document Type, which is used in Pega
7 applications by default. Rendering the user interface in HTML5 Document Type ensures cross-browser
and cross-platform compatibility, use of the latest HTML markup, and improved performance, among
other benefits. HTML5 compliance also ensures that we can take advantage of responsive screen,
dynamic, and column layouts that enables us to separate content from presentation.

The tool identifies and provides links to applications, harnesses, and rules that should be updated to the
HTML5 standard. In some cases, we can automatically upgrade all the instances from the landing page.
For example, we can use the Remove inline styles from all sections button to automatically update all
the sections on the list.

For more information about the tool, see the PDN article, Upgrading an Application to Render in HTML5
Document Type http://pdn.pega.com/node/22341

149
Using the UI Kit
The UI Kit is a stand-alone ruleset, named UI-Kit-7,that provides a sample end-user UI built using the
latest design trends and Pega 7 UI capabilities. With the UI Kit, we can leverage the most recent UI
capabilities in Pega 7 in our applications.

The UI Kit includes the standard Case Manager and Case Worker portals which we can use as is or as
starting points for creating and customizing our own screens. The UI-Kit-7 ruleset is not part of the
PegaRULES application and must be included in the application ruleset list.

Note: This ruleset is available on versions 7.1.6 and above and is included automatically in these
versions. Manually add the ruleset to Pega 7 applications that have been upgraded to 7.1.6 or above.

The UI-Kit-7 ruleset is published in a locked ruleset. To customize the portals provided in the UI Kit, we
must copy the entire contents to an unlocked application ruleset and remove the UI-Kit-7 ruleset from the
application ruleset list.

Each update to the UI Kit is published as a new major release. This also allows us to standardize on a
specific version of the UI Kit, and to control when we upgrade to a newer version while avoiding any
conflicts arising from the effects of rule resolution.

150
Other Tools
There are other tools provided in Designer Studio that can assist UI development.

Pega and Alert Log Files

We can use the Logs landing page available from Designer Studio > System > Operations > Logs to
monitor issues that may be impacting UI performance. For example, the PEGA0029 HTML Stream Size
alert indicates that the HTML stream sent to the browser is excessively large due to a screen that
contains too much content or contains a large list. To resolve the alert, consider:

 Splitting the screen into tabs or use multiple screens in a screen flow
 Modifying the grid results pagination

 Reducing the number of client-side visible when conditions

Guardrail Landing Page

The Guardrail landing page available from Designer Studio > Application > Guardrails provides a suite of
metrics for understanding compliance with best practices. Pay special attention to warnings related to UI-
specific rules such as sections, portals, and controls. For example, this warning on the Warning Details
tab points to an issue regarding an undefined format not defined in the skin rule.

Tracer Tool
Use the Stream Rules setting on the Tracer tool for debugging browser interactions. The Pega Platform
(PRPC) engine processes source HTML or XML text starting with an instance of rule types derived from
the Rule-Stream classs such as flow action, list view, section, correspondence, and so on.

151
Third Party Developer Tools
Consider using tools available in browsers such as Developer Tools (DevTools) included in Chrome.

DevTools are a set of web authoring and debugging tools that provide deep access into the internals of
the browser and their web application. Use DevTools to efficiently track down layout issues, set
JavaScript breakpoints, and get insights for code optimization.

152
Firebug is a popular, open source web browser extension for Firefox that allows us to inspect website
code and elements, and provides powerful HTML editing and debugging capabilities.

While not a tool, we should be aware of Accessible Rich Internet Applications (ARIA) which defines ways
to make Web content and Web applications (especially those developed with Ajax and JavaScript) more
accessible to people with disabilities. For example, ARIA enables accessible navigation landmarks,
JavaScript widgets, form hints and error messages, live content updates, and more. For more information
about ARIA and list of development resources see the MDN Aria page at https://developer.mozilla.org/en-
US/docs/Web/Accessibility/ARIA

153
 Module 06: Creating Dynamic UI

This lesson group includes the following lessons:

 What is a Dynamic UI
 Conditionally Hide or Show Fields in a Form
 Actions on Controls
 Displaying Calculated Fields in a Form
 Conditionally Display Fields as Read-only, Disabled or Required
 Defer Loading Fields
 Cascading Relationships on List Based Controls
 Grid Actions

154
 What is a Dynamic UI?

Introduction
Dynamic User Interfaces is a term that refers to the concept that UI content changes dynamically based
on a user’s interaction with the content. In this lesson we will look at a few examples of dynamic UI’s and
the benefits they bring. In subsequent lessons we will go into details on different approaches and how
they are configuration.

At the end of this lesson, you should be able to:

 Illustrate a Dynamic User Interface

 Describe the Benefits of a Dynamic User Interface

155
Illustrate a Dynamic User Interface
Let us start by looking at a few examples of dynamic UI. These examples show different cases of a
dynamic UI when the UI changes based on user input.

Show/Hide Fields
We have a form where the user enters his marital status. Depending on the martial status selected
different additional fields are shown. If the user selected single no additional input is required.

However, if the user selected married the fields for spouse and marriage date are dynamically added.

If the user selected divorced the divorce date field appears instead.

Required Fields
We have a form where a user can optionally enter their mobile number.

However, if the user selects to receive SMS notifications the mobile number is set to be required.

Disabled/Read-Only Fields
Below, we have a form where a user needs to provide shipping and billing addresses for an order. To
make it easier for the user, we have provided a checkbox so they can use the same address for shipping
as billing.

If the user selects the checkbox we copy the shipping address to the billing address and the fields are set
to read-only.

156
Alternatively, we could disable the fields resulting in the screen below.

Calculated Fields
In this form we capture the date of birth. The age is automatically calculated and displays as read-only.

157
Benefits of a Dynamic User Interface
Dynamic UI’s offer several advantages. Primarily they improve the user experience considerably. Static
UI does not suffice for all complex requirements. Having a dynamic UI makes the application more
purposeful and responsive because we display content that changes based on the user and the context.

It is extremely difficult to just use static UI screens to build an entire application. One of the challenges
with screens based on a static UI is that users need to click through or scroll through many screens to
find the content relevant to them and their purpose. With a dynamic UI we do not need to clutter the user
interface with unnecessary information. User forms are shorter since they only display information that is
relevant to the user.

In addition, we can refresh only a part of the screen, even a single cell so the changes appear
seamlessly. Users do not need to see an entire page refresh every time the UI is dynamically changing.
Technically, this is done using AJAX. This concept is very powerful and there is a wide variety of
supported events and actions.

158
 Conditionally Hide or Show Fields in a Form

Introduction
Users can often be plagued with too many options on the screen. This can be overwhelming and
confusing. A dynamic UI automatically adjusts which elements are seen. Hence, controlling the visibility of
components is an instrumental part of building a dynamic UI. In this lesson we will look at different options
to hide and show UI components.

At the end of this lesson, you should be able to:

 Configure Visibility
 Use the Condition Builder

 Describe the implications of Run on Client

 Configure Refresh Conditions
 Configure an Action Set to Refresh

159
Configure Visibility
Suppose we want to display the date of marriage cell only if the martial status is set to ‘Married’. Let us
take a look at how we might do this in Pega 7.

The visibility setting is the main mechanism to configure whether or not some part of the page is visible.
Visibility settings are configured on the General tab and are available on sections included in another
section, on layouts, and on cells. There are three options for layouts and sections.

For cells there are two additional options.

Visibility conditions can also be added on grid layouts. We can configure the grid to show or hide the
entire grid or just the header and footer.

160
The Visibility options are:
1. Always — there is no visibility condition on this field, layout or section.
2. If not blank — visible if the value of that field is not blank.
3. If not zero — visible if the value of that field is not zero.

4. Condition (expression) — uses a condition to determine visibility, visible when the

condition is true.
5. Condition (when rule) — uses a when rule to determine visibility, visible if the when rule
returns true.

We are using an expression to control the visibility of the marriage date property based on the selected
marital status. Note that we have the option to Reserve space when hidden if we want.

For the marriage date to show we need to do a server-side refreshed, or alternatively run the conditions
on the client side. We will have a look at both option.

Condition Builder
When we choose Condition (expression) in the visibility field, the system provides the option of using a
condition builder to write expressions. Click the Gear icon to open the condition builder.

In the Condition Builder we can configure an expression, for example, the marriage status property value
is equal married. It is possible to add multiple expressions using AND or OR. If we need to write more
than two expressions, it’s better to write it as a when rule.

The Condition Builder can also be configured to reference a when rule. When we choose a when rule, it
provides the option to select True or False.

161
Run on Client
When we use if not blank or zero, or expression, the Run visibility condition on client option appears.

What does this field mean? If this is enabled, the visibility condition fires on the client side. So at runtime,
the section code comes with a markup added to the hide/show part of the screen based on the condition.
If this field is disabled, the section code does not contain the hidden part and it requires that the section is
refreshed which means communicating with the server to get the hidden part where the condition is
satisfied.

Hence, selecting the run on client option reduces the number of server trips, but the HTML delivered to
the browser is larger since it contains the extra markup. Therefore, we should try to optimize the number
of server trips with the extra payload size for our particular use case.

The choice of client-side or server-side processing can have a significant impact on how the UI behaves
for end users, as outlined in the following table:

If run on client is not selected a server side refresh is needed. The remainder of this lesson presents
options for refreshing a section.

162
Refresh Condition
The Refresh Condition allows us to have a portion of a page return to the server to refresh its content
when a specified condition is true. Refresh conditions can be configured on either an included section or
a layout.

Here we want to use the shipping address for billing if the same as shipping checkbox is selected.

The layout is configured to refresh when the checkbox changes value.

Similar to the visibility setting, we can use the condition builder to add conditions. We can configure the
properties to respond to a condition and there is the option to use AND or OR to add more than one
condition. In addition to these, there are two keywords.

Changes – This indicates when the property’s value is changed, in this example, it refreshes when the
MaritalStatus is changed.

AddDelete – This applies only to repeating layouts. A refresh is triggered when an item is added to or
deleted from the repeating layout. Select a page list property in this field.

Adding a refresh condition allows us to optionally run a data transform and activity when the refresh
condition evaluates to true. The data transform and activity are run before the section is refreshed. If both
a data transform and an activity is specified the data transform is run first. In our case we specified a data
transform that copies the shipping address when the checkbox is selected or resets the values if the
checkbox is deselected.

163
We can also configure refresh of a specific row within grids. By default, the row never refreshes; we can
configure it to refresh on a specific condition.

164
Refresh Using an Action Set
Unlike visibility, a refresh condition can also be configured using an action set. We can use the Change
event to track changes to the properties specified in the cell. In our case we can define a change event
with a refresh action on the same as shipping checkbox.

The Refresh action allows us to specify one of the following targets:

 Section – refreshes the current section

 Other Section – refreshes the section specified

 Harness – refreshes the current harness
Similarly to the refresh condition we also have the option to run a Data Transform and Activity before
the section or harness is refreshed. If both a data transform and an activity is provided, the activity runs
after the data transform. In our case we specify a data transform that copies the shipping address when
the checkbox is selected or resets the values if the checkbox is deselected.

We also have the option to specify Conditions specifying when we want the refresh action to run.

We can select Disable submit on refresh if we don’t want to submit edited data to the clipboard. For
example, we could use this option with a reset button that either clears or reverts a form to its previous
state by populating it with data from the clipboard. In this case we want to refresh without any values
present in the form to be submitted.

165
 Actions on Controls

Introduction
A Dynamic User Interface refers to the concept that the UI content changes dynamically based on a
user’s interaction. In Pega 7, dynamic UI’s are configured in an event-action model. Let us look at this
with a simple example. When a user clicks the Refresh icon (Event), the screen refreshes its content.
(Action) A dynamic UI requires us to define both of them (the event and the action). When the event
occurs the action associated with it presents the change immediately to the user. This helps in creating a
user interface that provides a great user experience. In this lesson, we will learn about various actions
and events and how this model can be configured.

At the end of this lesson, you should be able to:

 Define Events, Actions, Action Sets

 Configure Action Sets with multiple Events and Actions

 Describe available Events, Actions and Conditions

166
Events, Actions and Action Sets
Let us start by looking at the event-action model.

Actions Sets
Events and their associated actions are configured in an Action Set. An action set must have at least one
event and one action defined. First, we will look at where we define action sets.

Controls – In most of the cases, we define action sets on controls. Action sets are defined on the
Actions tab of the Cell Properties form.

Grids – Action sets can also be configured on the Actions tab of the Layout Properties form for grids.

Action sets are comprised of events, actions, and optionally, conditions.

• Event — an action performed by the user.

• Action — an action performed by the system as a result of the user event.

• Conditions — restrictions that can be applied to an event and action combination.

167
We can define multiple events and actions within an Action Set and create multiple actions sets for a
control. Actions execute in the order in which they are listed. Use the row handles to rearrange the action
sets if necessary.

Some specific actions can also be associated outside the context of an action set. They are directly
configured on the part of the screen where we want the action to take effect. We can use these actions to
apply:

 A Visible when condition on a cell or a section or a layout to hide or show its elements based on a
condition.
 A Refresh when condition to refresh a cell or a section or a layout.
 A Disable when condition to disable the cell.
 A read only condition to make the cell read-only.

Events
Events are used to trigger an action that makes the user forms dynamic. There are a wide variety of
events available. Let’s look at few examples, when the user performs any of the following actions.

 Clicks a control such as button, link or icon

 Double clicks a row in the grid
 Right clicks on the entire grid
 Presses the Esc key in the keyboard
 Selects “MA” from the state dropdown

 Clicks the checkbox to enable or disable

 Enters “5” in the quantity field
That’s a little of everything. Events are defined in the action set.

168
Actions
Now that we know about where and how we can identify events, but what happens when that event
occurs? That is defined in Actions. Using the list of examples we saw earlier, let us see what types of
actions can occur.

 When the user clicks a control such as button, link or icon – it opens a new window.

 When the user double clicks a row in the grid – it opens the row in edit mode.
 When the user right clicks on the entire grid – it shows a menu.
 When the user presses the Esc key on the keyboard – it closes the assignment and goes back
to the home page.
 When the user selects “MA” in the state dropdown – it updates the list of counties.
 When the user clicks the checkbox to enable or disable – it unmasks the password.
 When the user enters 5 in the quantity field – it calculates the total.
The actions are also defined on the Actions tab on the Cell Properties form. Similar to the list of events, a
wider variety of actions can be configured.

169
Configure Action Sets with Multiple Events and Actions
A control or grid can have multiple action sets. An action set must have at least one event and one action
defined. In this section we are going to look at how we can configure an action set.

Multiple Action Sets

We can configure multiple action sets for a control or grid. A single event can be present in only one
action set for that control.

Imagine the following, in an insurance claims application there is a date of loss field. We need a smart tip
for this field. Depending on how long ago the loss occurred, we want to set a few parameters (properties)
based on that date which we will need later in the process.

In our case, we have defined one action set for the hover event showing the smart tip and another action
set to run a data transform that sets the values.

The action set can be configured to be applicable when the control is set to editable or read-only or both
editable and read-only. We want the smart tip to always be shown irrespective of the field setting (read-
only or editable). The change event on the other hand is only applicable when the field is editable.

Multiple Events for the Same Action

We can associate several types of events with the same action. In this case the action is performed when
either of these events occurs. This is useful, for example, when we need to add a keyboard event
corresponding to the mouse event in accessibility friendly applications. For example, we can get next
work by either clicking the button with the mouse or pressing enter on the keyboard when the button is in
focus.

170
One Event with Multiple Actions
It is also possible to associate several actions to an event or multiple events. For example, here we first
refresh the section and then set the focus when the value of the field changes.

The actions are performed in the order they are defined. In this case, the section refreshes and then the
focus is set. If we switch the order, the focus is set before the section refreshes.

171
Available Events, Actions and Conditions
Action sets are comprised of events, actions, and optionally, conditions. We will look at the type of events,
actions and conditions available.

Events
When we click Add an event the list of events for the control displays. The events available differ slightly
depending on the control. Events are divided into three categories: mouse, keyboard and other. Here we
see the events available for an input.

The button control has no change event since that event does not apply to a button.

For grid layouts a reduced number of events are available.

172
Actions
When we click Add an action a list of common actions appears. Actions are divided into six categories:
display, process work, launch, get work, list and other.

Click All actions to view the list of all available actions.

As we can see, there are a large number of actions available.

Conditions
We can apply conditions to an action. For example, we can configure a condition so that hovering over a
field displays a smart tip only if the field is populated.

173
To summarize:

 Active/inactive – Action is executed if the control is active or inactive, respectively.

 Empty/populated – Action is executed if the associated property is empty or populated,
respectively.

 Associated property/other property – Action is executed if the associated or given property is

equal to the given value.
 Required/not requires – Action is executed if the field is marked required or not required,
respectively.
 When rule – Action is executed if the specified when rule evaluates to true.
For example, if we want the smart tip to show only when the field is empty we can configure a condition
like this.

174
 Displaying Calculated Fields in a Form

Introduction
Sometimes we want to display calculated data to a user. For example, we might want to display the total
for an order that is calculated by adding the subtotal for each line item together. Pega 7 automatically
refreshes the relevant data on the screen if declare expressions are used for calculation. So we might
assume that using declare expressions is the preferred approach for calculations. However, calculations
can also be done procedurally using the refresh condition or an action set with a data transform and/or an
activity. In this lesson, we will explore the different options and learn when it is best to use each option.

At the end of this lesson, you should be able to:

 Describe the change tracking mechanism

 Use a refresh condition to update values on the screen
 Use an action set to update values on the screen

175
The Change Tracking Mechanism
The change tracking mechanism re-computes the value of properties that are the target in a declare
expression immediately after a user changes the source value in the expression in a flow action form,
rather than later when the form is submitted. For example, the target property, which is always presented
in read-only format, can represent a total. The total changes immediately as the user focus leaves an
input field that is used in calculating the total. This feature uses AJAX between the browser client and
server.

This feature is always enabled on flow actions with dynamic layouts. When you use this feature be sure to
include at least one input to the expression as another field on the flow action.

When a declare expression rule has Result of decision table, Result of decision tree, or Result of
map value for the set property field, special processing occurs at runtime when a property referenced in
that decision rule is not present on the clipboard. Ordinary such decision rules fail with an error message,
but in this case the system returns the Otherwise condition instead.

In this case the decision table returns the cost of shipping, which depends on the order total.

176
Using the Refresh Condition to Update Values on the Screen
There might be situations in which we prefer to compute values procedurally rather than with a declare
expression. The Refresh condition allows us to have a portion of a page return to the server to refresh
its content when a specified condition is true. Refresh conditions can be configured on either an included
section or a layout.

This layout is configured to refresh when the total changes.

We can use the Condition Builder to specify when the section should refresh. We can configure the
properties to respond to a condition and there is the option to use AND or OR to add more than one
condition. In addition to these, there are two keywords.

 Changes – This indicates when the property’s value is changed, in this example, it refreshes
when the Total is changed.
 AddDelete – This applies only to repeating layouts. A refresh is triggered when an item is added
to or deleted from the repeating layout. Select a page list property in this field.

Adding a refresh condition allows us to optionally run a data transform and activity when the refresh
condition evaluates to true. The data transform and activity are run before the section is refreshed. If both
a data transform and an activity is specified the data transform is run first.

In our case we specified a data transform that calculates the grand total.

177
Using the Action Set to Update Values on the Screen
We can also use an action set to calculate a value. First we need to specify a Change event to track
changes on each property that is part of the calculation. In this case that is the unit price and quantity
fields in the line item.

The Refresh action is used to calculate and refresh the screen. We have the option to refresh the current
section or another section or the harness depending on where the calculated value is contained.

Similarly to the refresh condition we talked about previously there is an option to run a Data Transform
and Activity before the section or harness is refreshed. If both a data transform and an activity is
provided, the activity runs after the data transform. In our case we specify a data transform that calculates
the line item subtotal.

178
 Conditionally Display Fields as Read-only, Disabled or
Required

Introduction
Sometimes we want to display non-editable data to a user. There are two options available in Pega 7, we
can either disable the input field or display a read-only version of the value. In this lesson we will look at
the difference between the disable and read-only options and how they are configured. We will also look
at how we can make input fields mandatory based on a given condition.

At the end of this lesson, you should be able to:

 Describe the difference between the disable and read-only options

 Disable fields
 Configure fields and sections to be read-only
 Configure fields to be required

179
The Difference Between Disable and Read-only
Disable prevents users from using the form element. The element is greyed out and cannot be selected
or changed and it is not possible to tab to it with the keyboard. Here is an example of a disabled
dropdown and button.

Disable is often used with checkboxes. For example, here we are ensuring that at least one of the
checkboxes is always selected.

Read-only displays the content of a property. For example, here we can see how it looks when the billing
address is copied from the shipping address and displayed in read-only mode.

The same screen would look like this if we used the disable option.

180
How to Disable Fields
Suppose we want to make sure that at least one of the checkboxes are selected. We can do that by
disabling the checkbox if the other two are not selected. Let us take a look at how we might do this in
Pega 7.

The disable setting is the main mechanism to configure whether or not an element is disabled. Click the
Gear icon to open the cell properties. Disable settings are configured on the General tab and are on cells.
There are four options.

The Disable options are:

1. Never — the field is never disabled.
2. Always — the field is always disabled.
3. Condition (expression) — uses a condition to determine if the field is disabled, disabled
when the condition is true.
4. Condition (when rule) — uses a when rule to determine if the field is disabled, disabled if
the when rule returns true.

Condition Builder
When we choose Condition (expression) in the visibility field, the system provides the option of using a
condition builder to write expressions. Click the Gear icon to open the Condition Builder.

In the Condition Builder we can configure an expression. It is possible to add multiple expressions using
AND or OR. If we need to write more than two expressions, it is better to write it as a when rule.

181
The Condition Builder can also be configured to reference a when rule. When we choose a when rule, it
provides the option to select disable when it returns True or False.

Refresh
For the field to be disabled we need to either refresh the section on the server side, or alternatively “Run
the conditions on the client side.”

What does this field mean? If this is enabled, the disable condition fires on the client side. So at runtime,
the section code comes with a markup added to the hide/show part of the screen based on the condition.
If this field is disabled, the section code does not contain the hidden part and it requires that the section is
refreshed which means communicating with the server to get the hidden part where the condition is
satisfied.

Hence, selecting the run on client option reduces the number of server trips, but the HTML delivered to
the browser is larger since it contains the extra markup. Therefore, we should try to optimize the number
of server trips with the extra payload size for our particular use case.

The choice of client-side or server-side processing can have a significant impact on how the UI behaves
for end users, as outlined in the following table:

Review the pages Refresh Condition and Refresh using an Action Set in the lesson Conditionally hide or
show fields in a form for details on how to refresh a section.

182
How to Make Fields Read-Only
Sometimes we want to ensure that certain fields are read-only. The Edit options setting are the main
mechanism to configure whether or not an element is read-only. The Edit options settings are configured
on the Presentation tab on the cell properties. There are five options.

The Edit options are:

1. Auto — the field used the edit mode of the component in which appears.
2. Read-only (always) — the field is always read-only.
3. Read-only (expression) — uses a condition to determine if the field is read-only, read-only
when the condition is true.
4. Read-only (when rule) — uses a when rule to determine if the field is read-only, read-only if
the when rule returns true.

5. Editable — the field is always editable.

Let us have a look at an example using the auto edit option. Here we include a section in a dynamic
layout.

We have the option to specify the edit options for the included section on the Presentation tab in the cell
properties. The options are the same as for elements. The cells with an edit option set to auto in the
included section inherit the edit option setting on the included section.

183
We can use the Condition Builder to define an expression for read-only in the same way we did for
disable. See the Configure Disable page for more details. Note that there is no run on client option for
read-only.

The Read-only value dropdown allows us to specify what to show when the element is read-only.

There are four options:

1. Property value – displays the value of the current property

2. Another property’s value – displays the value of a specified property
3. Constant – displays a given constant value
4. Localize Property Value – displays a localized version of the property value
It is possible to specify a Type for the Read-Only Format. This is the option available for text input.
Selecting Email, Phone, or URL renders the content as a link. Clicking on the link opens the
corresponding application.

Depending on the type selected there might be additional configuration available. For example, selecting
Date or Date/Time allows us to specify the format.

Similarly, selecting Number allows us to configure relevant details.

184
How to Make Fields Required
Sometimes we want to ensure that certain fields are provided. We can do that by marking them as
required. Fields marked as required display with an asterisk next to the field label.

The required setting is the main mechanism to configure whether or not an element is required. Click the
Gear icon to open the cell properties. Required settings are configured on the General tab on the cell
properties. There are four options.

The Required options are:

1. Never — the field is never required.

2. Always — the field is always required.
3. Condition (expression) — uses a condition to determine if the field is required, required
when the condition is true.
4. Condition (when rule) — uses a when rule to determine if the field is required, required if
the when rule returns true.
We can use the Condition Builder to define an expression for required in the same way we did for disable.
Required also has a run on client option, which works the same as it does for disable. See the Configure
Disable page for more details.

185
 Defer Loading Fields

Introduction
By default all components of a page are loaded inline with the page on which they are displayed. This
means that the page does not display until all the components are loaded. Sometimes we want to defer
the loading of certain parts of a page to speed up the response time. This is especially the case when
parts of the screen that do not need to display initially or are rarely displayed or are expensive to build. In
this lesson we will describe the different options for deferred loading.

At the end of this lesson, you should be able to:

 Describe the different loading mechanism

 Decide when to defer loading

 Configure defer loading

186
Describe and Configure Lazy Loading
Lazy loading is a common design pattern that defers initialization of an object until the point at which it is
needed. Pega 7 allows us to configure lazy loading in several places. For example, the content of a tab
can be loaded when the tab is selected.

Similarily n the content of a collapsed section can be loaded when it displays for the first time.

Select Defer load contents to enable deferred loading for the component that does not initially display.
Selecting this option ensures that the component will not loaduntil it needs to displays. We have the
option to Specify a pre-loading activity that runs prior to the deferred part loading. The pre-loading
activity can be used to compute property values and other aspects of the deferred component.

187
Defer the Loading of Part of a Page
The Defer load contents setting used earlier to configure lazy loading can also be used on components
that are not initially hidden. For example, here we have a screen with a note field and an address, which
is very expensive to retrieve.

We can defer the loading of the dynamic layout holding the address.

When the screen is rendered the note field immediately displays while the adress is still being loaded.
That is, the case item displays first and then the defer loaded sections display as they become available.
The UI is not blocked while the address is loaded. Hence, we can take action on the case while the
deferred content is still being loaded.

Once the address has been loaded the screen displays with the address.

188
For this to work we need to source the data we want to defer the loading of from a data page. Pega 7
loads data pages asynchronously by default, which means that Pega 7 uses a different browser
connection than the main requestor servicing the case item.

In our particular case, we have an address property that sources by a data page.

This is useful when pulling external data from systems or records, web services, and other systems,
because it is expensive to retrieve the data since it allows users to work on the screen before all the data
has finished loading.

189
Configure Paging
When using a grid control we have the option to spit the list in blocks called pages and display them as
they are needed rather than displaying the entire list. This improves performance since it limits the
number of rows initially loaded, thus rendering the screen more quickly. If we are displaying data in a grid
that comprises more than a single page we should consider using paging. Pagination is enabled on the
General tab on the layout properties on the grid.

There are two alternatives when using pagination; Progressive and Traditional. In both cases the
clipboard is loaded with all the data during the initial load. The remaining items are loaded in the UI on
demand. We can use a custom pagination activity to limit the clipboard size when retrieving large
amounts of data by populating the clipboard incrementally. The pagination activity can also be used to
control sorting and filtering behavior. The standard template activity pyTemplateAdvancedGridActivity can
be used as guidance when configuring the parameters.

190
Progressive Pagination
The Progression pagination presents a single page of data that initially contains a specified number of
items. Additional data displays as users scroll through the list. Thus, progressive paging enables users’
access to the entire data set by scrolling. In addition, it allows users to act on the full data set when re-
ordering data by dragging and dropping, sorting, and filtering.

Select Progressive as the Pagination format to enable progressive paging.

Traditional Pagination
The Traditional pagination presents a set of pages with the data set allowing users to navigate between
the pages. There are four page navigation control formats. The page navigation control is not displayed if
the results produce less than one page.

This is how the different formats look.

Page 1 of X

Page 1, 2, 3…

191
Rows 1 - Y

First X Results

192
 Cascading Relationships on List Based Controls

Introduction
Sometimes we want to filter the contents of a control, such as a dropdown or autocomplete, to only
display records that match something selected or entered in a different control. This lesson explains how
to create two cascading controls. The selection of a value in one control directly impacts the contents of a
second control. The approach presented in this lesson can be extended to cascade to include any
number of controls.

At the end of this lesson, you should be able to:

 Describe common use cases

 Configure cascading controls

193
Common Use Cases for Cascading Controls
Sometimes we want list controls to be filtered based on a user’s previous inputs. A typical example is
countries and states. When a country has been selected we only want to display the applicable states in
that country.

Although it is most common to cascade list controls, such as dropdown and autocomplete, we can feed
any value onto a list for filtering. Here we are using the value of a radio button selection to filter a
dropdown.

194
Configuring Cascading Controls
Let us have a look at the configuration for the above examples. The country and state lists are maintained
as local data storage.

In this case we can source the dropdown from a data page or report definition.

We source the dropdowns from the data pages generated for us when creating the local data sources.
The country dropdown is sourced from the D_CountryList data page as generated by the system.

Hence, for the D_StateList data page, which holds the list of states we need to add a parameter for the
country code. This way we can feed in the selected country. This parameter needs to be propagated to
the report definition.

195
When configuring the dropdown control for the state we now need to specify the country parameter.

196
 Grid Actions

Introduction
In the lesson Actions on controls we looked at the action-event model in Pega 7 and how we can
configure it for controls. In this lesson we start by looking at how we can use the action-event model in
grids. We then look at how we can extend the grid update mechanism by customizing the behavior.
Finally, we look at how we can configure row visibility and refresh conditions.

At the end of this lesson, you should be able to:

 Configure action sets on grids

 Extend the grid update mechanism

 Configure row visibility and refresh

197
Configure Action Sets on Grids
The action sets are configured on the layout properties, which can be opened by clicking the Gear icon.

When the grid is added three standard action sets are automatically configured. An action set must have
at least one event and one action defined.

If we enable row editing on the Operations tab, two additional action sets are automatically added.

We can add new or modify the standard action sets to fit our requirements. An action set must have at
least one event and one action defined. The following events are configurable for grids.

198
When adding an action, the common actions display first..

Click All actions to display all available actions. The actions relevant for grid operations are in the List
category.

The action sets configured on the grid itself are applicable for the entire row. In addition, it is of course
possible to define events and actions on individual cells in the grid. For example, we could add a delete
icon to the row.

The action set defined on the cell would then look like this.

199
Extend the Grid Update Mechanism
The grid update mechanism can be extended and customized by specifying activities under the Advanced
Configuration on the Operations tab.

It is possible to run an activity on both rows add and delete. This allows us to define custom logic, such as
prepopulating a row with default data when adding it.

It is also possible to run activities before and after the grid is updated . Two template activities are
provided for customization. The activities have in the @baseclass and are called pyPreGridUpdate and
pyPostGridUpdate.

The activities contain a step for each type of grid action allowing us to easily extend and customize the
activity for a specific action. This is an example of how a when condition looks like.

200
Configure Row Visibility and Refresh
We have the option to hide and refresh a row on a specific condition. The settings can be found on the
General tab.

We can use the condition builder to configure the visibility and refresh conditions. We can configure the
properties to respond to a condition and there is the option to use AND or OR to add more than one
condition.

In addition there are two keywords for row refresh.

Changes – This indicates when the property’s value is changed, in this example, it refreshes when the
Product is changed.

AddDelete – A refresh is triggered when an item is added to or deleted from a page list property.

201
 Module 07: Presentation

This lesson group includes the following lessons:

 Introducing the Styling Concept

 Skin Basics
 Styling Layouts
 Styling Controls
 Styling Grids
 Container Styling

202
 Introducing the Styling Concept

Introduction
A web application is made up of content and presentation. We spoke about content earlier, so now we will
switch gears and discuss presentation.

In this lesson group we will focus on the presentation layer, starting with high level presentation concepts,
and then go into details about the construction of the skin rule and its application in styling UI
components.

At the end of this lesson, you should be able to:

 Understand the concept of the presentation layer in web applications

 Articulate how the presentation layer is implemented in Pega 7
 Create, reference, and preview skin rules

203
Presentation vs Content
In modern web applications there is a clear separation between content and presentation. Content is the
information provided by the application or webpage, and presentation refers to how the information is
presented to users.

In terms of web technology content is the HTML, presentation is the Cascading Style Sheet (CSS). HTML
contains semantic annotations for the data content, CSS controls presentation by changing color, size,
font, and positons of the UI elements. They work together to render a web page.

In the example below of the New York Times website we see the difference with and without a
presentation layer.

Although content can live without presentation because the application or web page will continue to
provide the same information. But, a presentation layer provides the visual styling appropriate to the user
and the rendering device. Presentation is an important part of a good user experience.

When we create a web page or an application, we always start with data. For example, in designing a
page for displaying customer information, we start by listing the data we want to present.

204
But data in its raw form is not how we want it to appear to the end user. It needs to be organized so
users can understand it and quickly learn.

Below we organize the data with a layout into a form that is familiar to the user.

With the data organized in a structural layout we have the content layer completed.

Next, we apply styling to the content to further improve readability and fine tune visual details. In this
case we emphasize the name with a larger font size and a brighter color, and de-emphasize the address
field labels with light grey to give the field values more focus. Also putting the labels on top instead of on
the side of the fields makes the interface more compact and makes it easier for users to consume the
information.

Notice that the labels all use the same style: the same font size, the same font style, and the same font
color.

Suppose we have a company that sells office supplies and we want the customer information and product
information to be visually consistent on our web site. To do this we would apply the same styling to the
customer information and the product information.

205
Any styling change we make affects both the customer information and the product information. For
example if we change the color of the title text and increase the font size of the field values the style of
both the customer information and the product information updates automatically.

This is a classic example of the separation of content and presentation. We apply a presentation to the
content, and when the presentation changes, the user interface automatically changes. We define the
font size, font color, etc. once, (as a single definition) and associate it to different pieces of content.
When that single definition changes, everything changes.

Now, let us learn how the presentation layer is implemented in Pega 7 - what artifacts it consists of, and
how they are created and configured to style an application.

206
Presentation Layer in Pega 7
The UI content layer contains data elements and structural elements. In Pega 7 applications, this layer
includes everything from the outermost portal, to sections, to layouts, to individual controls, to navigation
and everything in between.

The presentation layer consists of skin rules that specify the presentation of the content, including
typography, borders, backgrounds, layouts, and UI placement and alignment.

A Skin rule is comprised of mixins and component style formats.

A mixin is a style pattern that defines typography, border, or background, or a combination of these. It
can be reused to create other mixins and style formats.

A style format is a group of styling attributes that provides presentation style for components, such as
dynamic layouts, or controls, such as buttons and links.

Mixins and style formats are reusable styling components with cascading increments. They alleviate the
need for inline styles and custom CSS, and provide the ability to achieve branding and styling consistency
throughout the application.

The UI capabilities in Pega 7 have been designed with front end design and development methodologies
in mind. A primary principle when designing user interfaces is to separate content from presentation
(HTML from CSS), or in our case the section (which provides the content) from the skin (the source of the
presentation).

207
Formats are defined in the skin and the content merely points to a format in the Skin rule. This allows for
easy maintenance and change when required. We can alter the content without needing to touch the
presentation and alter the presentation without altering the content.

The configuration possibilities in a Skin rule associate closely with the general concepts of web
application presentation. Earlier we mentioned the box model. In CSS each element is a box and layout is
constructed by putting rectangular boxes together. We will see how this is achieved in a Pega UI when
we talk about styling layouts and containers in the skin rule.

The parameters of the box model can all be configured in the Skin rule.

When configuring a border styling, for example, users can set the values for the border style in a drop
down box, and the border weight in a text input. The styling effect is immediately available on the right for
preview.

And the border color is selected in a color picker.

208
Take typography styling as another example. Here a textual heading style is configured by setting the font
family, font size, font color, font weight, and so on.

The Skin rule has a friendly user interface for configuring the presentation. Developers do not have to be
proficient in styling scripting as the system automatically generates the entire CSS for the application.

209
Skin Rule
Beginning with Pega 7, Skin rules are associated with an application and a portal. Here is the skin
reference in an Application rule.

By default, a portal points to the skin specified in the application, ensuring that all portals in the
application have the same look and feel. This is a best practice since it enables greater reuse and
consistency across the application.

But we do have the ability to override the default skin for cases where we may want to display a different
look and feel, such as for external vs internal users.

Skin rules belong to the User Interface category. Use the Records Explorer to list all skins available in the
system. A new Skin rule can be added by clicking the Create button or copying an existing one and
modify.

210
Select DesignerStudio > User Interface > Portals and Skins to see the portal-skin associations in the
current and built-on applications.

Other than in the Application rule and in the Portal rule, operators can setup a preference for a particular
skin, via Operator Preferences, and override the skin of the Designer Studio.

This preference can be used for previewing or testing an application during development. The skin set
here is applied to processes initiated from the +Create menu and any harness, section, or flow action that
developers open, edit, or preview.

Conclusion
The best practice in creating modern user interfaces is to separate the content from presentation—that is,
separate the HTML from the CSS. This separation ensures greater UI consistency and promotes reuse, it
also makes development and maintenance of web interfaces more efficient.

In this lesson, we learned that in Pega 7, the presentation layer is implemented in Skin rules and how
they are referenced by other rules to provide styling for an application.

Later other lessons, we will take a closer look at different parts of the Skin rule and its mechanism in
styling specific UI components.

211
 Skin Basics

Introduction
The presentation layer of Pega 7 applications is implemented in the Skin rule. We can style all
presentation elements of the interface in the skin, including typography, borders, backgrounds, layouts,
and UI placement and alignment. All presentation requirement can be fulfilled in the skin without
tempering the content layer. For example, a company changes its branding and needs to apply a different
color scheme to the application, this can be achieved by applying a different skin to the application
without making any changes to the content layer.

Mixins and formats are the building elements of skin rules. We use them to construct incremental styling
changes with a natural cascading sequence. These increments provide consistency and ease of
maintenance, they also promote reuse.

At the end of this lesson, you should be able to:

 Articulate relationships among components, formats, and mixins

 Create and reference style formats for UI components
 Create and configure mixins for UI styling

212
A Cascading Styling Pattern
This video explains the basic concepts of formats and mixins, and how they work together to create
cascading styles.

213
Formats
A style format is a group of styling attributes that provides presentation style to UI components. In Pega
7 style formats are defined for components, such as dynamic layouts, or controls, such as buttons and
links.

Let us look at the button control as an example to better understand the relationship between formats and
UI components.

To see the style formats defined for buttons go to the Component styles tab in the Skin rule, click on the
component selection dropdown and select Buttons.

The out-of-the-box skin rules are shipped with a small number of formats for each type of UI component,
with the default one named Standard or Default. Here we see that three formats are defined for buttons:
Standard, Simple, and Strong.

They are listed in the Style formats column on the left. The middle column shows the parameter values for
the styling configuration. The right column shows the formats in preview. The preview function is very
convenient enabling developers to see the styling effect of the formats. It can be set to preview either the
currently selected format or all the formats which makes it easy for us to compare them.

214
The default set of formats on each type of UI component cannot always satisfy the styling requirements of
an application. To extend the existing styling options we can always create new custom formats.

To create a new format, either click the Add new style link at the top of the Style formats column and
create the new format from scratch, or right click on any existing format and select Clone to copy it and
then make modifications.

Here we have a custom format called Light defined for buttons, in addition to the three pre-defined
formats.

As shown in the screen shot below, the three pre-defined style formats for buttons are available for
reference in the property panels for sections, harnesses, and controls. In addition, the Other option is
used to reference custom style formats.

215
When we select the Other option another dropdown appears for selecting a custom format. Here we have
chosen the custom format Light that we just created.

216
Mixins
A mixin is a style pattern that defines typography, border, or background, or a combination of these. The
Mixins tab in the Skin rule has three columns. The left column lists all the defined mixins, the middle
column is where we configure the styling for the selected mixin, and the right column shows the preview
of the selected mixin.

The General mixin provides a base format for typography styling. Its definition includes font family, font
size, font color, font weight, and so on.

Mixins are reusable style patterns. They can be reused, via reference, to style different user interface
components such as buttons, links etc. And it is a best practice to define style formats using mixins. When
we talked about style formats in the last section we saw that the Standard button format is defined by
referencing this General mixin.

217
Mixins are also reused, via inheritance, to create other mixins. For example, the Link mixin is created by
inheriting form the General mixin and overriding the font color from black to blue. Which means any
changes to the General mixing styling, except the font color, will carry over to the Link mixin.

This inheritance chain continues with the Strong Link mixin which inherits from the Link mixin and
overrides the font weight to be Bold. Which means any changes to the Link mixing styling, except the font
weight, will carry over to the Strong Link mixin. In other words, the override styling attributes “block” the
corresponding styling attributes of the parent. This is true to both mixin inheritance and style format
reference.

We will see the effect of this inheritance and override mechanism in an example, later in this lesson.

Mixins are grouped into four categories: Typography, Backgrounds, Borders, and Combinations. Mixins in
the first three categories can inherit from other mixins in the same category. Since a mixin in the
Combinations category affects more than one of the other categories, it can inherit from any other mixins.

Once you define a mixin and set its category you cannot change the category. You can either rename it
or delete it.

The styling effect of a mixin can be previewed in the right column in the Mixins tab. The “Preview with”
dropdown lists all the mixins and components that reference the selected mixin. The reference can be
through mixin inheritance or style format reference. Here is the list for the “Strong Link” mixin.

218
After selecting a component in which to preview the mixin, click Details to view a summary of where the
mixin is used within the component styles.

We can change the styling of a mixin at any time. A change to a mixin cascades throughout all its children
mixins and the style formats that reference this mixin.

Let us see what happens when we change the color of the mixin Link from blue to red.

In the preview column we can see that not only the color of the mixin “Link” changes, this color change is
propagated to mixins and style formats that have references to the “Link” mixin. The “Strong Link” mixin
inherits from the “Link” mixin without overriding the color styling, thus it gets the color change too, as
shown below.

219
But the color change does not take effect in the mixins and formats where the color styling is overridden.
Here we have a custom style format “Soft” for the link component whose color does not change.

Looking into the definition of the style format “Soft” we see that it does reference the “Link” mixin but it
overrides the font color with grey. This override blocks any color change in “Link”.

With this mechanism of inheritance and override, we can create incremental styling changes which
provide a natural cascading of styles; and using mixins and style formats helps ensure consistency
across the user interface, maximizes reuse, and minimizes future maintenance.

220
Conclusion
In this lesson we learned how to build incremental styling changes with formats and mixins.

We recommend that you follow these best practices, while building the presentation layer of the
application:

 Separate the presentation from the content – move styling attributes of HTML elements to skin
rules, group them into reusable formats, associate UI components with formats.
 Extract common sets of styling attributes among different formats into mixins.
 Name mixins and formats by their purpose, rather than their stylistic appearance.
 For a given component create formats as few as needed, to avoid maintenance cost.

221
 Styling Layouts

Introduction
Layouts are structural elements that hold UI content inside sections. Every section contains at least one
layout. In Pega 7 newer layouts such as dynamic or column layouts are available for creating structured
web design and they are styled entirely in the skin.

Now that we have a basic understanding of the skin rule, let us take a look at its application in styling the
layout components.

At the end of this lesson, you should be able to:

 Configure style formats for dynamic layouts

 Create UI forms with nested dynamic layouts
 Configure style formats for column layouts
 Configure style formats for layout groups
 Configure dynamic layout to use floats

222
Dynamic Layouts
A dynamic layout provides us with flexibility when displaying content.. The style formats defined in the
skin determine item and label placement, alignment, and spacing within the layout. They also define the
responsive behavior of the layout.

The configuration settings for dynamic layout formats are organized into four groups: Layout Settings,
Label Settings, Item Spacing, and Responsive Breakpoints.

In the Layout Settings group we define how the UI components are arranged on the screen. We can
define the Width, Maximum Width, Minimum Width, Item arrangement (inline-grid or inline), Column per
row, Minimum item height, and Vertical alignment.

Click the “about this” link to the right of the field title to see a graphical explanation of the item
arrangement concept.

The “Column per row” setting is applicable for an inline-grid type of arrangement.

223
Item arrangement can be one of two types.

 Inline arrangement allows for adding fields in a row that flows "inline" like the words in a
sentence. 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.

 Inline-grid arrangement displays the items inline in a multi-column grid. The inline grid triple, for
example, arranges items in three columns.

A number of out-of-the-box dynamic layout style formats are available in the skin,
including: Default, Stacked, Inline, Inline grid double, and Inline grid triple.

An inline-grid with one item per row is essentially a stacked layout.

224
The inline grid double format has two columns per row.

The Vertical Alignment setting defines item placement in relationship to the available row height. In terms
of the CSS box model, we can think of the layout row as a box into which the item is placed, and this
setting decides how the placement is adjusted vertically inside this box.

Below is an example of an inline middle layout. The third row shows the effect of vertical alignment
“middle”.

225
Below the Layout Settings group is the Label Settings group which governs the placement of field labels.

Label position options are: none (not shown), to the left of the field, or on the top of the field.

When labels are shown, they can be horizontally aligned to the left, in the center, or to the right of the
available space.

226
In the Item Spacing group we configure the amount of space around the displayed items. This setting
decides the margin space in the box model configuration. In the example above of the inline middle
layout, if we think the elements are placed too close to each other and it looks a bit crowded, we can
increase the Top and the Right spacing,

And the items will look less crowded.

Dynamic layouts can be added to a section either as individual components or as a Repeating Dynamic
Layout, as shown in the modal dialog when we add a layout to a section.

227
A Repeating Dynamic Layout basically is a dynamic layout that is tied to a list. It uses the displaying
format defined in the Dynamic Layout and the contents of the layout repeat for each item of the list.

The Repeating Dynamic Layout is perfect for displaying lists in a variety of different ways. And since it is a
Dynamic Layout, it is completely stylable and responsive. The following example shows a Repeating
Dynamic Layout that automatically adjusts for different display medium.

228
Nested Layouts
In CSS styling each element is a box and the layout is constructed by putting rectangular boxes together.
We can put not only UI elements like buttons and text inputs inside a Dynamic Layout, but other Dynamic
Layouts as well to create nested layouts.

Forms with nested Dynamic Layouts conform intelligently to available space, meaning that related fields,
or groups of fields, retain their intended relationship when the outer layout adjusts automatically to screen
dimensions.

Here we have two inline layouts 1.1 and 1.2 nested inside stacked layout 1. Depending on the screen
size, the elements inside the two inner inline layouts might wrap around into multiple rows, but the
elements inside each inner layout always stay together, and the element group of the layout 1.1 always
display above the element group of the layout 1.2.

Nesting layouts is a powerful tool to create highly dynamic web forms. We can nest any number of
Dynamic Layouts with any depth level. Below is an example of a nested layout with a depth of two levels.

229
Column Layouts
Column Layouts present information in columns split vertically. They are ideal for displaying supporting
content, in the sidebar(s) alongside the main content, in the main area.

You may choose to display the primary content, such as a business case, in the main area and
supporting content in a sidebar. The supporting content gets a set width, and the primary content takes all
the remaining space.

Variations of the main area and the sidebar(s) combinations provide us with different types of column
layouts:

 Two Column (Sidebar-Main)

 Two Column (Main-Sidebar)

 Three Column (Sidebar-Main-Sidebar)

Column layouts are designed so that the sidebar gets a set width, and the main area stretches to take all
the remaining space.

230
Dynamic columns work well when we have primary and related supporting content - for example, a
product description in the main area and price and sizing information in the sidebar.

231
Layout Groups
Layout groups let us organize a lot of information into groups that display in different panes. It allows
users to view groups of related data one pane at a time, which in turn allows designers to modularize
these information groups in a compacted manner, saving valuable screen real estate.

The Skin rule form, as any other rule form in the Designer Studio, is an example of layout group with
tab navigation. The content is organized into four groups: Component styles, Mixins, Included styles,
and History.

As we learned earlier, we can specify the display pattern of a layout group as Tab, Accordion, Stacked, or
Menu.

The styling parameters for these different layout group formats are organized in a similar fashion in the
skin rule. Take the Accordion style as an example. The default settings for text, border, and background
styling is defined in the General tab. These default values provide a base styling for the layout group
overall and they are overridden, if necessary, to provide cascading styling changes for specific
components in the layout group.

In this example the check box “Allow opening of multiple panes” applies specifically to the accordion style.
We select this check box if we are creating an accordion that can have multiple panes open at the same
time.

The middle tab is to control-specific styling for the display type. Typography and Backgrounds settings for
the accordion divider bar are further divided into sub groups: Active, Inactive, and Hover. Control in
different status should be styled differently to give users clear visual queues of the mouse action. Shown
below we can see the different background color for the accordion dividers of different active status.

232
In the same Accordion Styling tab we see that the expand/collapse icons in the accordion divider bar can
also be customized.

The Content tab defines styling for the text content inside the active layout group panel. Here the active
tab content in a tab layout group is styled with a border of rounded corner in color green, and a grey
background color in gradient.

233
Floats

234
Conclusion
In this lesson we learned how to style different types of layouts by studying some of their standard style
formats defined in skin rules.

We saw how the configuration of different layouts is related to the CSS box model concept and how these
layouts can be used to create highly dynamic user interfaces.

235
 Styling Controls

Introduction
Controls determine how properties appear on user forms, for both display and user input. Pega 7 comes
with standard controls which can be styled in the Skin rule.

Although styling settings like typography, border, or background can be applied to all UI elements, they
have different implications in the context of styling specific controls. We will review some commonly-used
controls and discuss the styling options that are unique to each of them.

At the end of this lesson, you should be able to:

 Configure styling formats for Button controls

 Configure styling formats for Link controls
 Configure styling formats for Dropdown controls
 Configure styling formats for Text inputs & Formatted Text

236
Controls
Pega 7 comes with a list of standard controls. To see this list click on the component dropdown in the
Component Styles tab of a Skin rule.

Each of these controls has a unique look and function. For example a dropdown is a clickable element
that provides a list of items from which users can select, and a link that is clickable text or an image that
takes users to a target URL. We will explore some of these items to demonstrate their unique styling
options.

237
Configuring Buttons
A button is an action control that can be configured to perform one or more actions when clicked. The UI
Gallery is a great source of implementation examples where we can see buttons with a variety of styles
and perform various actions.

Styling buttons requires making changes both in the Skin rule and in the section containing the control. In
the Skin rule we can specify the height of the button and the style of the text, border and background. We
saw earlier in the Skin Basics lesson how to use mixins to style button text. Here we will focus on the
border and background styling.

A button can have no borders, or borders with solid, dashed, or dotted line styles.

In this example, we have used a solid red border style. The changes can be viewed in the preview pane
of the Skin rule.

238
Buttons can also be styled to use rounded corners. This is configured right below the Border style section
in the Skin rule. Check the same x and y axis radii check box to have symmetric roundness for the
corners.

For asymmetric rounded corners, we need to specify different radii for the x-axis and y-axis.

Next let us look at the four options that are available for styling the background styles of a button. None
as the name refers does not apply any background color on the button.

239
With solid as the background type, we can configure a different color for different statuses of the button.
Here, for example, the button is highlighted with the color Blue when it is depressed, and it becomes
transparent when it is disabled.

With gradient as the background type, the background color is blended gradually from the Start color to
the Stop color, and the blending direction can either be vertical or horizontal. We recommend that a
backup color be specified in the event that the browser cannot render the gradient.

We can use the image option for the background type and then use images to configure the left, middle,
and right to construct the button. Note that the Tile setting for the middle image defines how the image is
repeated to fill the space, and the Position setting defines the starting point of the repeat. In this
example, a narrow vertical image is repeated horizontally, starting from the top-left of the space to form
the middle section of the button.

240
Do not confuse these left, middle, and right images for the button background with the image that we can
insert next to the button label. The latter is configured in the section rule.

Now let us see what we can configure in a button control in a section. The caption that appears on the
Button is configured in the control.

We can also insert an image next to the button caption, as shown below.

In the Presentation tab, we choose a format defined in the skin rule for the button control. We can also
include a label for the button.

241
Configuring Links
Link is another action control that we can configure to invoke one or more actions when users click or
hover the mouse pointer over the text link. Again, we can open up the UI Gallery to see examples of links
with a variety of styles and dozens of common actions.

Let us look at some of the specific configurations for links. The two configurable aspects of link formats
are Normal Text and Hover Text. We can give them the same style by checking the Use same
formatting for Normal and Hover text check box at the top of the configuration form, or we can
distinguish them with different styles. In the following example, we promote the hover text with a bolder
font weight, an underline text decoration, and an uppercase text transformation, in order to give users an
obvious visual queue for mouse action.

The options for text decoration are:

And the options for Transform text are:

242
In configuring a Link control in a section, we can insert an image or add a label to it the same way we did
for a Button control.

We can see that the Link and Button controls share most of the same capabilities, the differences are
mainly in their presentation.

Given the general convention of web interface that a "link" takes a user to a web-address, we should be
careful to use the link controls in such a way that it does not confuse the users.

243
Configuring Dropdowns
A Dropdown control displays a list of items when a user selects the control. A single item can be selected
from the list and this selected item displays in the dropdown box. Similar to buttons we can create formats
and apply them to a dropdown added in the section rule. Let us take a look at another configuration that is
specific for dropdowns.

The list items in a dropdown can be categorized into groups. In defining dropdown formats in the Skin
rule, we can style the list item text and the group by text differently to distinguish them. In this example,
we have a dropdown displaying skin rule names grouped by ruleset names. The group text, in this
example the ruleset names, has a different color than the list item text to enhance the visual effect.

The list items grouping of a dropdown control is specified in the Section rule. For the dropdown control in
the above example, we see in the section configuration that grouping is enabled by checking the Group
items check box.

244
Configuring Text Inputs & Formatted Text
Earlier when talking about styling controls, we saw most of the general options for styling text. For
example, with mixins, with mixin overrides such as text decorations and text transforms, or with specific
styling definitions. These options can all be applied when styling Text Inputs & Formatted Text.

Style formats defined here apply to following types of text:

 Field text - is text that users type in a text input or a text area
 Placeholder text - when the text input or the text area is empty
 Character counter text – when number of characters or remaining characters allowed
 Read-only text – when a text input or a text area is displayed in read-only mode
 Error text – error message on an input field when users make a mistake
In the Skin rule, the styling effect on these texts is previewed in the right pane, as shown below.

We can create a one-for-all format by checking the Same formatting for Field, Error, Remaining
Counter, and Read-Only Text check box, at the top of the styling configuration pane, or we can clear
this check box to define styles for each of these elements individually.

For border and background styling, we suggest that you select the Use browser styles for border and
background check box, below the text configuration section, to take advantage of styling features built
into browsers. Clear this check box to override the browser styles and specify settings for field and error
borders and backgrounds.

Conclusion
Buttons, links, dropdowns, and different types of text elements are commonly used in building
applications. In this lesson we learned about styling options that are unique to each of them. Knowing
these options gives developers powerful tools to build and enhance the presentation layer of an
application.

245
 Styling Grids

Introduction
Quite often we need to present arrays of data in a repeating fashion. For example, to list product function
features and prices in a tabular format, or to present employee reporting hierarchy in a tree format. Users
also need to perform data operations such as sorting, filtering, row reordering, and so on.

In Pega 7 the repeating grid layout is ideal for such purposes and the styling configurations offers many
possibilities to rendering the data. We will discuss the styling of repeating grids both in the Skin rule and
in the Section rule, and how they relate to each other.

At the end of this lesson, you should be able to:

 Configure style formats for Trees & grids in the Skin rule
 Configure presentation for Trees & grids in the Section rule

246
Configuring Grids in the Skin Rule
Grid, Tree Grid, and Tree layouts are variations of the repeating layout that we can use to present values
from a Page List or Page Group property, a report definition or a data page.

 A Grid layout presents data in aligned columns and rows, as a spreadsheet.

 A Tree layout presents hierarchical data in the form of an expandable tree. Users can expand
and collapse branches of the tree to find entries of interest.
 A Tree Grid layout, as its name suggests, combines the navigation strengths of a tree with the
quick-access data display of a grid.
Many working examples of these repeating layouts can be found in the UI Gallery. The following sample
one uses a tree grid to display employee information, including reporting structures.

These repeating layouts present a rich set of UI elements: rows, columns, row headers, column headers,
header and footer, and so on, all of which can be styled in the Skin rule. The pre-defined Trees & grids
formats (Default, Spreadsheet, and Transparent) give us great options for styling an application.

To see the difference we apply these formats to the same data set. The Default format promotes row
headers with a background color and divides rows with visible borders; the Spreadsheet format does
away with header coloring and distinguishes grid items with cell borders in addition to row borders; and
the Transparent format displays no borders at all.

247
The styling settings for Trees & grids are categorized into six groups: General, Rows, Headers, Borders,
Behaviors, and Action Layouts.

General Tab
The General tab looks similar to what we have seen in the Layout Groups format. Here we can use text,
border, and background mixins to define a default set of styling that can be used in other configuration
tabs for different UI components. The responsive behavior is also configured here.

Rows Tab
In the Rows tab we define styles that apply to the rows in grids, tree grids, and tree layouts. A nice styling
feature is called zebra striping which alternates odd and even rows with different visual styles.

This feature is enabled by selecting the Enable row banding options (zebra striping) check box and
differentiating the Odd rows and Even rows with different styles.

In configuring row styling both Text and Background can be specified using the default style defined in the
General tab, a mixin, or a custom style.

248
We can also specify Expand and Collapse images for Tree icons and Expand Pane icons. In the
employee information tree grid layout at the beginning of this lesson, the down arrow expand image
indicates a manager row is expanded to show his subordinates.

Expand Pane icons and Tree icons are specified in the same way. To configure the Tree expand icon
click the configuration icon and select an image from the Image Catalog.

Headers Tab
In the Headers tab we define styles that apply to the column and row headers in a grid, tree, or tree grid
layout. We can specify text, background, border, and images that indicate column sorting and filtering and
row handles.

In this example the check box Use same formatting for column and row header is cleared to enable
different styling for column and row headers. The row header distinguishes itself with a solid color
background.

249
Graphical icons are used in the column and row headers to give users visual clues about the current
status of the data. For example, the Sort indicator tells the sorting order of a column, and the Filtered icon
indicates whether a filter has been applied to the column data. The images of these icons can all be
configured in the Headers tab. In the following example, a red-colored image is selected for the Filtered
icon and a black-colored one for the Unfiltered icon.

The repeating grid layout has six configuration tabs, the ones not shown already can be accessed by
clicking the dropdown menu.

Behaviors Tab
In the Behaviors tab we can configure styling associated with UI events on grid items. The configuration
points include:

 Text and background of a grid row when the row has focus or is selected
 Style of text in a row when the mouse pointer hovers over the row
 Border, background, and images associated with drag and drop behavior within the grid

250
In this example, we can rearrange the grid items by dragging and dropping a row to a different position.
The red row is currently in focus, indicated by a blue text font and a grey background color. When we
move it down to just above the yellow row, the dotted green border line indicates the targeted dropping
position, and the blue arrow sibling image indicates that the red row will be a sibling of the yellow row
after the drop.

Action Layouts Tab

In the top and bottom areas of a repeating grid we can place buttons or other controls linked to actions,
such as Add Item or Delete. The styling for the top and bottom areas is configured in the Action Layouts
tab.

251
Configuring Grids in the Section Rule
In addition to the Skin rule, the Section rule has a few settings related to the styling of repeating grids as
well. We can configure them in the Layout Properties modal dialog.

General Tab
In the General tab some of the visual aspects of a repeating grid like pagination and visible conditions are
configured. The Header and footer settings determine whether, and under what conditions, the top and
bottom actions areas display. The style settings of the Action Layouts in the Skin rule are applied to these
action areas.

Presentation Tab
In the Presentation tab a Trees & grids style format can be selected from the Style dropdown to apply to
the grid.

The Width of content setting determines whether the widths of the columns within the layout (both action
and repeating areas) are set as a percentage or in pixel values. In the following example when the grid
width changes from the Fill (100%) setting to the Pixels (Fixed) setting, the width of the grid is limited to
250 pixel, and users need to use horizontal scrolling to view the full content of the grid.

252
To override the default presentation when a grid is empty, check the Display custom message when
there are no rows to display check box. We can use either a custom section or a custom field value for
the message. Similar customization can be applied to the display when there are no results upon filtering.

Operations Tab
The settings in the Operations tab determine what grid item operations are available to users. Some of
these operations affect the grid presentation. When column sorting and filtering are enabled, the sort and
filter icons display in the column headers, these icons are configured in the Headers tab of the skin
format, which we talked about earlier in this lesson. When row reordering is enabled, users can rearrange
individual rows in the grid, the visual indicators of drag and drop, like target row background color or
dropping position border line, are styled with settings defined in the Behaviors tab of the skin format.

Conclusion
In this lesson we discussed how to configure styling for repeating grids both in the Skin rule and in the
Section rule, and how they relate to each other.

This gives us great options for styling an application when displaying large amounts of data with repeating
grids.

253
 Container Styling

Introduction
In a web interface, each UI element is placed inside a container in one form or another. A container
should have a visual style appropriate to its function. For example, a navigation panel container should
render its content in a straightforward, low-key fashion, without distracting users’ attention from the main
work area; while a warning message container should have a visual style that alerts users.

Dynamic layouts and repeating grids that we discussed in earlier lessons are all different forms of
containers. In this lesson we will discuss how to configure container formats that apply to these layouts
and grids, and conclude our discussion of the presentation layer.

At the end of this lesson, you should be able to:

 Configure style formats for containers in the Skin rule

254
Configure Containers in the Skin Rule
In the context of the CSS box model, dynamic layouts and repeating grids can all be considered
containers that have other UI elements arranged inside, as is the case with nested layouts which we
discussed earlier.

The Containers formats in the Skin rule define styling settings, such as padding and margins that
determine how the inner elements are placed inside the outer boxes.

These formats are referenced from the Section rule to apply to layouts and grids. For dynamic layouts,
the Container format is configured in the General tab; for repeating dynamic layouts and repeating grids
it is configured in the Presentation tab.

In the Skin rule, a container format has three configuration tabs.

 Header - Styles set here apply to container header

 Body - Styles set here apply to the body of the container below the container header
 Outline - Styles set here apply to the entire container as a whole
Since we are already familiar with configuring individual styling settings such as text, borders,
background, images, and so on, we will discuss the configuration of these tabs by demonstrating their
visual effects.

255
Headers Tab
In the Headers tab we define text, border, background, expanded and collapsed icons, height, and left
padding for the header items in a container. The left padding setting determines the indentation of the
headers. Here we have a format named Warnings with the left padding set to 0 pixels.

Another format named Column has the left padding set to 7 pixels. We can see how the headers shift
slightly to the right compared with the left edge of the body text.

The Skin rule has quite a few pre-defined container formats that provide a variety of visual styles. We can
find examples of their application in the Case Manager portal. The Recent history section is rendered with
a repeating grid layout styled with the Explorer format, the header bar has a low-key light grey font color;
the Team member section is rendered with a dynamic layout styled with the Default format, the expanded
header has a stronger text font than the Recent history header, and note the expanded icon image to the
left of the header text.

256
We can find more examples by inspecting the configurations of different layouts in the portal using the
Live UI tool.

One of the pre-defined container formats is named Hidden. We use it to style nested hidden layouts to
align content without using a header. For example, in this user form for travel reservation, the Maximum
price and Number of guests inputs are placed inside an inline grid double dynamic layout. We want to add
an input for the number of children but it should be placed below the Number of guests input, not below
the Maximum price input.

This can be achieved by placing an empty layout, styled using the Hidden format, below the Maximum
price input and add the new dropdown for the Number of children input as the next element in the
containing layout.

Body Tab
The most important aspect to set in the Body tab is the padding. We can define the same padding on all
sides or different padding for different sides.

257
To see the visual effect of the padding settings, we set the body of the Default format to have a visible
border and then we compare its preview with no paddings and preview with 15 pixels padding on all
sides, indicated by the red arrow.

Outline Tab
The border settings for the outline applies to the border that encompasses the whole container, which is
different from the border around the body text. For the sake of demonstration, we set the outline with a
red border.

The most important aspect to set in the Outline tab is the margin. Margin refers to the empty space
cleared around the whole container. Same as the padding setting in the Body tab, margin can be set as
same for all sides or different for each side.

Here we compare the difference between a margin of 5 pixels and a margin of 35 pixels, same on all
sides. The green rectangle is the outer box inside which the container is placed.

258
Conclusion
The styling settings for containers are particularly relevant to the CSS box model. In this lesson we
reviewed these styling settings and showed the visual effects of different container formats, and their
applications in the Case Manager portal.

This lesson concludes our presentation layer studies.

259
 Module 08: Validating User Inputs

This lesson group includes the following lessons:

 Introduction to Validation
 Client Side Validation
 Server Side Validation
 Customizing Error Messages

260
 Introduction to Validation

Introduction
Ideally, users enter information into a web form in the correct format and finish their job successfully.
However, people often make mistakes. This is why validation is important.

At the end of this lesson, you should be able to:

 Understand the importance of validation in a Web application

 Distinguish client side and server side validations and the pros and cons of each

261
Server-side and Client-side Validation
Data validation is important in all web applications. Before accepting data, we need to ensure that all the
required information is submitted, and that the submitted data conforms to the correct formats and
business rules. This is important because we want our application to be secure and we want our users to
have a great user experience.

From a security perspective invalid data can cause unexpected execution errors, break assumptions
elsewhere in our application, and even let someone hijack our service to attack others. From a user
experience perspective a good validation design prevents user errors in the first place, and when the
errors do happen the system guides the users to correct such errors and complete their tasks efficiently.

There are two types of validation: server-side validation and client-side validation. Each has its
advantages and disadvantages.

Server-side Validation
In server-side validation a web form is submitted and the information is sent via the network to the server
and validation is performed on the server side. If the validation fails the response is sent back to the
client and the web form is refreshed with the feedback.

Server-side validation is secure because it does not depend on JavaScript being turned on in the web
browser (the client) and it cannot be easily bypassed by malicious users. On the other hand, it requires
round-trip network communications between the client and the server and this might result in a slow
response to the user. The exception is when we use Ajax for validation because Ajax calls to the server
can provide immediate feedback as our users enter information into the form.

Client-side Validation
Server-side validation might suffice for security reason, but for a better user experience, however, we
should consider using client-side validation.

With client-side validation, user inputs are validated on the client side and a web form never gets
submitted if the validation fails. Users get immediate feedback on their errors. By using script languages
such as JavaScript a user’s input is validated as they type. This means a more responsive, visually rich
validation.

The main drawback of client-side validation is that it is bypassed if users turn off JavaScript on the client
side. This is why we recommend that validation be implemented both on the client side and on the server
side. By combining server-side and client-side validations we benefit from both of them: fast response,
more secure validation and a better user experience.

262
What to Validate
Let us take an example to see user input validation in action. Below is the web form that a user needs to
fill out to register for a Gmail account.

Required Information
The first and most obvious information that should be validated is the required information – information
without which the operation cannot be successfully completed. Thus, validation has to ensure that the
user provided all the necessary details in the web form and it has to fail if at least one of the fields is not
provided. In the Gmail registration, if the user tabs out from the First Name field without putting in any
value an error message reminds him that this is a required field and cannot be empty.

Required fields should be clearly marked in order to inform users about what information has to be
provided up front. A common way to mark required fields is with an asterisk (*). However, if all fields are
required, as in the Gmail registration form, there is no need to place any marker on the form.

263
Correct Format
Apart from ensuring that users provide necessary information, validation should ensure that users provide
information in the correct format. This applies to such things as an email address, URLs, dates, phone
numbers and others. In the picture below we see that the phone number format has failed the validation
and the user is asked to reenter the value.

We see in the same web form that the user input for birthday month and phone number country code is
done using a dropdown. This is another technique of data format validation – users are forced to select
values in correct format from a dropdown instead of entering them in free text form where they are likely
to make mistakes.

Month dropdown:

Phone number country code dropdown:

264
Confirmation Fields
When working with data that is important to the system, it is a best practice to let the users confirm their
input using additional confirmation fields. This way users can be certain that they provided the correct
information. A typical case when confirmation field is used is for passwords, as implemented in the Gmail
registration form.

Instant Validation
As in any user account system the Gmail system must make sure that there is no duplicate username. If
the user requested a username already in use, the user will be notified immediately as shown below. The
username availability validation is done using Ajax calls to the server and the response is available as the
user types without having to submit form.

Validation Feedback
If validation fails, the system should let users know by providing clear and unambiguous messages and
ways to correct errors. As we see in the case of Gmail registration, when the user submits the registration
form all input fields are validated and feedback is provided. The user has all the information they need to
correct their errors.

265
Best Practices for Validation Design
We discussed different techniques of user input validation. There are many possibilities and not all
techniques provide a solution for everything. We should carefully plan validation for each project. Below is
a short list of considerations when creating validations in your design.

 Never omit server-side validation.

 Do not let users think about what information is required, always clearly mark required fields.
 Do not provide confusing validation feedback. It should clearly communicate the errors and ways
to fix them.
 Never provide validation feedback on a single page.
 Do not use dynamic effects as compensation for a badly designed form. Fancy effects will not
hide a poorly designed web form.
 Do not forget to inform users when the form is completed successfully. It is as important as a
good validation feedback.

266
 Client Side Validation

Introduction
With client-side validation, user inputs are validated before the form is submitted enabling users to get
immediate feedback on their errors.

For example, if a user is completing a form and the quantity field is set to accept only integers then
entering a string or decimal would be detected right away and an error message appears immediately
before the user clicks Submit.

In Pega 7 there are many options to configure the user interface with client side validation and force users
to enter the proper values. This is a win-win scenario – it is simple for users because they are prevented
from entering anything wrong and it is good for the system since it always gets data in a valid format.

At the end of this lesson, you should be able to:

 Configure required field validation

 Configure validation via property definition
 Configure validation via control configuration
 Enable client side format validation
 Describe the approach of validating using custom JavaScript

267
Identify Mandatory Fields
One of the most common requirements is to make sure users enter values for all of the required fields.
Let us see how this requirement is addressed in Pega 7 using client side validation.

Here we have a simple section for collecting data for booking a trip, and we would like to make some of
the data fields required input.

If the section is built using the Form Builder, we can configure the required fields in the Form Builder as
shown below.

268
Regardless of whether the section was originally built in the Form Builder, we can configure the required
fields in the section rule itself. As shown below, we can open the Cell Properties configuration and specify
that the Origin data input is a required field.

In the case where the display of the field is customized in the section by using a different control than the
default one defined on the property rule, the field can be configured to be required only under certain
conditions. In the example below, the condition is implemented with an expression. This can also be done
with a when rule. Make sure to check the “Run required condition on client” check box to enable client
side validation.

269
Once a field is configured to be required, it is rendered with an asterisk marking to identify that input is
mandatory.

If users tab out of the required field without entering a value, the validation fails and the field is marked
with an error message that prevents the form from being submitted.

270
Property and Control Validations
Defining the properties with the appropriate data type and using a control that restricts users from
entering invalid data goes a long way in making sure users enter valid data.

A property rule not only provides the premise to define a data element but is also useful in making sure
the valid data is collected. The property rule form offers various ways to enforce validation.

When defining a single value property we must specify its data type. The data type determines the valid
values the property can accept. For example, a date field can only allow date values, and a decimal field
rejects values with letters. Below is the list of data types that can be assigned to a single value property.

If the property is of type Password, Text, or Identifier, we can configure the max length validation in the
Advanced tab on the rule form as shown below.

271
Controls are used in configuring the presentation of data elements as well as validating user inputs. In the
following example a text property “Sex” is configured to be rendered as a dropdown control; the dropdown
control is sourced with a prompt list of distinct values Male and Female.

The dropdown control makes sure the user selects a correct value without the need for further validation
on the data.

272
Here is another example with the Date time control. As shown below, we can specify that text entry is not
allowed for data input.

What this means is that users must select a date from a graphical calendar rather than entering a literal
string value.

The entered data might need to go through further validation to make sure it satisfies some business
requirements, but we can at least be sure that the data entered is in the correct format.

273
Client-side Format Validation
Validation of a Value mode property always includes testing its value against the formats allowed by the
Type and its maximum length. To provide stronger validation for this property, we can use an edit validate
rule. This is configured in the “Use validate” field on the Advanced tab of the property rule form.

An edit validate rule in itself belongs to server side validation, a topic we will cover in the next lesson. But,
many standard edit validate rules are emulated by an equivalent JavaScript function that can be run on
the client side.

By default, the client-side format validation is enabled on all forms, so the fields using edit validate rules
are validated before the form gets submitted.

274
Validating Using Custom JavaScript
In the rare case where we have to perform client side validation with custom JavaScript, first we need to
implement the validation logic in a JavaScript file, include it in the harness rule, and then invoke the
validation logic from the HTML code of a non-auto-generated section.

A custom JavaScript file can be included into a harness with configuration in the “Scripts & styles” tab of
the harness rule.

The script file can be an individual JavaScript file or Static Content Bundle file which is a collection of
individual files as shown in this desktopwrapper bundle.

Once the JavaScript file is included in the harness, the JavaScript functions implementing validation logic
can be invoked directly from the HTML code of a non-auto-generated section rule.

275
Conclusion
In this lesson we learned how to implement various types of client side validation. This includes the
mandatory field check, data type and maximum length check, enabling edit validate on the client side,
and control level validations. We also talked about how to incorporate a custom JavaScript file to perform
client side validation.

276
 Server Side Validation

Introduction
Server side validation is necessary when validation requirements go beyond data format correctness. In a
flight reservation application, users enter information including departure date and return date. We can
use client side validation to make sure that these date are required fields and that they are in a valid
format, but for more advanced business requirements we need to use server side validation.

For example the departure date must be a future date and the return date cannot be before the departure
date. For the first requirement we can use an edit validate rule on the departure date definition and for the
second requirement we can use a validate rule to validate the relationship between the two dates by
comparing their values.

Validation can be performed at both the field level and the form level. In general form is validated on the
server side while individual fields are validated on the client side.

At the end of this lesson, you should be able to:

 Configure and reference a Validate rule

 Reference Edit Validate and Edit Input rules in a Property rule form
 Configure declarative validation
 Configure table type validation in Property rule form

277
Validate Rule
The most prominent technique of server side validation in Pega 7 is the Validate rule. A validate rule can
test the validity of multiple input values at once, and the tests are built using easy-to-understand "If-And-
Or" logical expressions rather than Java code.

The main part of a validate rule is configured in its Validate tab. It consists of a list of validating conditions
applying to different properties.

To build a validating condition we use the dropdown control to select an available function. The system
will evaluate this function at runtime to decide the outcome of the validation.

Multiple conditions can be combined together with logical AND or OR, as you see in the example above.

There is a Required check box at the top of the previous form. When it is checked server side validation
of required field will be performed. Do note that whenever possible mandatory field checks should be
performed on the client side, because the required field asterisk gives users a clear visual queue and the
validation error feedback is immediate without having to submit the whole form.

There is a Continue validation check box at the bottom of the form. We should have it checked if we
want the system to continue the rest of the validation even if this validation fails.

The validation condition builder is context sensitive to the mode of the property for which we are
constructing validation. For a page mode property the validation condition is built by calling on a validation
rule already defined on that page class.

278
It is possible to define in a validate rule different sets of validation conditions to be applied depending on
the value of an input property. This is configured in the Input tab. In the following example the validation
can be triggered conditionally base on the value of the property Origin.

Now back in the Validate tab, we can add additional columns to configure conditional validations based
on the value of the Origin field.

The same idea applies to other types of input value validation conditions. Please refer to the Help file for
configuration instructions.

Now that we know how to configure validate rules, let us see where we can reference them to trigger
these server side validations.

279
A validate rule can be referenced from a flow action rule and will be triggered upon submit of the flow
action. If validation fails the system will prevent the flow action from proceeding to the next step.

A validate rule can also be chained from another validate rule as shown below.

280
Edit Validate Rule
For properties of mode “Single Value”, “Value List”, or “Value Group”, another option for server side
validation is the “Edit Validate” validation. An edit validate rule defines a Java routine that tests the validity
of an input value. Normally, if user input fails such processing, the input is rejected and a red X appears
next to the input field in the error along with messages that may convey more about the error and the
suggested remedy. Users can change the input and resubmit the form.

Edit validate rules can be referenced from the Advanced tab of the property rule form. We can select any
of the standard edit validate rules using the “Use Validate” dropdown.

Here is the edit validate rule referenced from the previous property definition.

281
There are more than 60 standard edit validate rules. You can use them as is, or copy and tailor them for
your needs. The table describes a few of them.

Use the Records Explorer to see a complete list of the edit validate rules available in the system.

Since building edit validate rules and edit input rules (see following section) require Java programming
knowledge, an architect is rarely asked to perform such tasks. Most often property validation
requirements can be fulfilled with the standard edit validate and edit input rules shipped with the product.

282
Edit Input Rule
In the Advanced tab of the property rule form there is an “Edit input” field right above the “Use validate”
field. Here we can reference an edit input rule to perform data format transformation on the property
value. Technically an edit input rule is not a validation rule since it does not perform validation or reject
data base on certain conditions, but it does perform the necessary transformation to keep the data in a
valid format, and it does trigger validation on the property value when it is executed.

Here is the toUppercase edit input rule referenced in the property rule form that we saw earlier. As you
can see the logic is implemented in Java programming language.

In this example the Destination field is configured to use the toUppercase edit input. Users enter in a
value in the field and then submit the web form.

On the server side the data is formatted into upper case by the edit input rule.

283
Here are a few examples of standard edit input rules.

Use the Records Explorer to see a complete list of the edit input rules available in the system.

284
Declarative Validation
The system can also be implemented in a declarative manner. Constraints rules define and enforce
comparison relationships among property values. The system evaluates constraints automatically each
time a property identified in a constraints rule is changed. This technique is known as “forward chaining.”

If a property is present on the clipboard and fails a constraint, the system automatically adds a message
to that property. No other rules explicitly reference constraints rules. When we save a constraints rule, the
system enforces it immediately and thereafter.

Here is what a Constraints rule looks like. The constraint logic is configured in the “Constraints” tab.

The first row checks for a When condition. Here we are checking whether a property has a value. The
second row is the constraint condition. Here we are enforcing that the property has a non-negative value.
The third line, “Else add message” allows us to add a specific message to be associated with that
property or another property if the constraint fails. Like many other rules, we can use or build our own
expressions for the when and constraint conditions.

As the example shows, a constraints rule can contain multiple constraint conditions.

Because constraint validation is enforced automatically by the system every time the property’s value
changes, it could have a performance impact. Therefore, it is critical to evaluate the potential impact
before choosing this type of validation.

285
Table Type Validation
One way of validating user input value is to specify a set of acceptable values for a field. At runtime, the
system compares the input value to the specified set, verifies whether the value has a match.

A property of mode “Single Value”, “Value List” or “Value Group” can use "table validation" to constrain an
input value to match one of the specified values or a pattern of values. You define a "table of data" that
describes what values are valid for this property. Below is the list of available options in the “Table type”
dropdown list in the General tab of the Property rule form.

If the property value is permanently limited to a modest number of known values, we can use a local list
for validation, and we have already learned how to do this in the lesson “Sourcing List Based Controls”.
Let us see some of the other options in table type validation.

For a property holding the value of an existing operator we can validate its value against the key values of
the operator class Data-Admin-Operator-ID, as shown below. When you select Class Key Value, Table
Description fields appear. Complete them to identify a range of keys in a class other than the Applies
To class of the property you are defining.

Make sure the “Display only (not for validation)” check box is cleared so that validation is actually
enabled, otherwise the values defined for the selected table type are used only for SmartPrompt and
output localization, and not for validation.

In the previous example the Data-Admin-Operator-ID has only one key value defined. For using validation
class with multiple key values please refer to Help for detailed instructions.

Whereas Class Key Value specifies a class to validate the input values against, Remote List specifies a
particular instance of a class to validate against.

286
In the following example of remote list validation configuration, the “Keys of instance” section at the
bottom is where you enter key values that the system will use to identify the class instance that contains
the property value, which in turn holds the set of values to be validated against.

Conclusion
In this lesson we discussed various techniques of server side validation. Among these techniques the
validate rule is used most often because:

 Validate rules are easier for non-programmers to design and understand. Edit validate and edit
input rules require Java programming skills.
 Validate rules are more connected with the business process and the user interface, because
flow actions and case designer can call them.
 Validate rules simplify application design, because one validate rule can verify multiple input
values at once.
We also need to balance the choice between client side validation and server side validation. Too much
validation either on client side or on server side can have a negative impact on system performance and
user experience.

287
 Customizing Error Messages

Introduction
Error handling plays an important part in user experience. When errors happen, throwing stack trace and
exceptions without explanation will cause confusion and is not considerate to the user. In order to help
users understand errors and how to correct them, we must provide error messages that are polite,
precise, and constructive.

The display of validation error messages in Pega 7 can be customized with different configurations, thus
providing options to achieve better user friendly error handling.

At the end of this lesson, you should be able to:

 Articulate different types of errors

 Customize form level errors
 Customize field level errors

288
Types of Errors

The error handling of an application needs to deal with two types of errors in general: user errors and
system errors.

User errors refer to errors originated directly from a user’s action. For example when the user puts in an
alphabetic value for a field of integer type, when a user puts in a date in the past for the date of travel
reservation, or when a user does not provide required information in a user registration form.

System errors refer to errors at the system level. For example the loss of database connection, the loss of
network connection, or when a remote SOAP service becomes unavailable.

Validation errors belong to the user error category. When we talk about user input validation, this is
usually related to a web form where users enter input values. In the context of a web form, validation
errors can be categorized as field level errors and form level errors.

Field level errors are errors associated with a specific field; form level errors are errors regarding the
whole form.

Consider the following as an example of a field level error. To make a flight reservation, the user needs to
enter a date for the trip and the system will make sure that this date is a date in the future. If the user
enters a date in the past it will fail the validation and an error will be displayed, usually right next to the
input field, reminding the user of the “future travel date” requirement.

289
In the same flight reservation scenario, for the reservation to be a valid travel schedule, the return date
has to be after the departure date. Failure of this validation can result in either a field level error on one of
the dates or a form level error regarding the relationship between the two dates.

The login error that we have all seen is an example of a form level error. Here the error is rendered at the
form level instead of labeling out individual fields that might cause the login failure, because we do not
want to give any hints on how to tackle the authentication system.

Field level and form level validations apply to different use cases.

Field level validation is usually for keeping data in valid format, and form level validation is usually for
keeping multiple data values in a valid relationship. Form level validation can involve multiple fields
regardless of whether these fields are displayed in the current form.

290
Customize Error Messages in Harness
We can configure how validation error messages display to users. This is done through the Display
Options tab on the harness rule. Form-level errors are reported against properties not present on the
current form. By default the messages appear in a standard form-error message section. The error
messages can be displayed in three different ways.

Default shows the standard error section both at the top and bottom. Top of harness shows the standard
error section at the top of the form only. The configurable section allows us to display the messages in a
custom section that we create and place on the harness. Specify the name of the custom section in the
Custom Error Section field.

The custom section should contain text to inform users of any errors plus the standard section
@baseclass.ErrorList.

Use the Visible When feature on our custom section to make sure it is only shown when the When rule
has Messages returns true.

Let’s have a look at field-level errors.

Field-level errors are reported against properties on the current form and can be displayed in two ways.
As image with tooltip is the default and displays a red X next to field errors with the error message in a
tooltip. As full error text displays the full error text appears next to field errors.

If “Always Show” is selected the standard form-error section is shown even for field-level errors. This
means that both field-level and form-level errors display. Select Keep error display visible to cause the
entire runtime work item to scroll vertically as a single unit, except for the button bar and the form error
area which remains visible at the top.

291
Customize Error Messages in Skin
The appearance of error messages can be customized in the Skin rule form.

In the “Component styles” tab of the Skin rule select Errors from the component selection dropdown, as
shown below.

Here we can see the different display configurations that are supported for error messages. The
configuration effect is previewed on the right hand side.

292
For the field level validation, the image that appears on an error can be customized to use a different one.
In the Fields tab, the Icon field refers to this image.

To change this image simply click on the configuration icon and choose a different one from the Image
Catalog. You can reference a custom image file that you have created in advance to replace the default
field level error message icon.

Conclusion
In this lesson we talked about form level and field level errors in a web application, and we learned how to
customize the display of these two types of error messages in the Pega application.

293
 Module 09: Designing Screens

This lesson group includes the following lessons:

 UI Elements in a Screen
 Creating Your Own Portal
 Building Personalizable Dashboards

294
 UI Elements in a Screen

Introduction
Screens provide the framework in which we manage and monitor our work. Sometimes referred to as
portals (Designer Studio and Case Manager portal, for example), screens typically include controls,
reports, widgets, menus, and other facilities that enable us to perform a wide variety of actions. Screens
can allow us to view and create cases, reassign cases among users, monitor case status, and generate
Management reports. We can design screens to suit the specific needs of our users such as customer
service representatives, case managers, sales representatives, claims adjustors, and so on. Pega
provides design capabilities that give us the power and flexibility to build responsive screens that meet
almost any need.

At the end of this lesson, you should be able to:

 Use Live UI to discover the elements on a screen

 Define the screen layout
 Describe how skin rules are used with screens
 Describe how we use access groups and access roles to control screen presentations
 Describe available browser tools and how they can be used to debug and extend screen
presentations

295
Using Live UI to Explore a Screen
A screen is built from a portal rule, harness rules, section rules, and a skin rule. The screen that users
see depends upon the harness defined in the portal rule. For instance, the pyCaseManager7 portal
shown below displays the pyCaseManager7 harness when users open the application.

Content resides within sections. Layouts within the sections are structural elements that hold and
organize your content. Pega includes purpose-specific layout types for use in different situations.

We can use the Live UI tool to examine the individual elements built into a screen. The tool can help us
better understand how we can organize sections and dynamic layouts allowing us to take advantage of
controls, navigation rules, dashboards, widgets, and other features described in other lessons.

Starting the Live UI Tool

To use the Live UI tool, launch the screen we want to examine by selecting the launch menu on the
Design Studio header.

When the screen appears, click the Live UI button located on the bottom left corner of the screen.

296
In our example, we will examine the standard Case Manager portal.

Activating the Live UI tool displays a sidebar that contains a fully expanded hierarchical tree of all the
elements on screen.

At the top of the hierarchy we see the pyCaseManager7 harness and the three panel sections.

Here is how they are organized on the screen.

297
We can click on an item in the tree to highlight it on the harness. In the example below, we select the
Portal Navigation section (pyPortalNav) in the tree to locate it. Beneath the section node on the tree on
the right side of the screen we see that the Portal Navigation section contains dynamic layouts and
embedded sections for each of the three areas on the panel on the left side of the screen.

We can drill down to see the contents of a section. Below we see that the Recents section (pyRecents)
contains a repeating grid layout.

298
We can examine the pyRecents section wireframe in Designer Studio by clicking the magnifying glass
next to the name to open the rule. Here is how the layout appears in the rule.

Embedding Harnesses
In addition to embedded sections, we can also embed harnesses within the portal harness in order to
dynamically present work areas based on selection criteria. For example, let us select the Dashboard
item on the navigation panel located on the left side of the screen. When we look at the pyPortalContent
panel section, we see that we are presented with the contents of another harness called pyDashboard07.

Now we select the Reports item on the navigation panel and see that the section switches to the
pyCMReportBrowser7 harness.

A navigation rule, which is described in another lesson, controls which harness displays.

299
Defining a Screen Layout
When we open a screen we see a harness organized into a single screen layout. A screen layout
consists of a main panel and adjacent panels each identified by position: header, left, right, and footer.
Each panel of the screen layout can contain a single section.

When we create harness for our screen, we begin by selecting the screen layout we want to use.

For example, when we select the Header Footer Left Right screen layout the harness appears as shown
below.

300
Here are the three sections in the Case Manager portal as they appear in the harness rule.

301
Using a Skin Rule for Screen Presentation
The skin rule used with the screen enables us to define the presentation of elements. Presentation
elements include typography, borders, backgrounds, and so on, as well as the presentation aspects of
layouts. These presentation aspects can determine the flow of content within the layout, among other
things.

At the top of the Live UI hierarchy tree, we can quickly identify the skin associated with the screen we are
viewing.

Clicking the name opens the rule in Designer Studio. The skin contains styles that are especially useful
when designing screens such as Container or Screen layout styles.

We can customize the presentation for our screens by creating a skin rule and specifying it on the
screen’s portal rule, which overrides the default application skin.

302
Controlling Screen Displays
The screen users see when launching the application depends on which portal rule is defined in the
access group to which the user belongs. Our application can have any number of screens based their
access groups.

For instance, we might have an access group for case managers. We would design a portal for
managers only, which we specify in the Available portals list. In the example shown below, we have
specified the standard pyCaseManager7 portal.

Controlling the Display of Sections

We can also use access roles to control the display of sections in our screens. For example, we can have
same header section for various users and then use the manager or user role so that managers see a
section that users cannot see. We use a when rule or privilege or even the access group itself to control
the display.

Let us assume that we want to hide the Stages Report on the portal so that is visible only to work group
managers.

303
We would open the section’s properties panel and specify a privilege pyUserIsWorkGroupManager.

A user without the privilege would not see the Stages Report section.

304
Using Browser Developer Tools
Browser developer tools available in Chrome, IE, Firefox, and Safari can help us:

 Debug scripts on your pages

 Inspect the DOM structure in order to perform tasks such as attaching a CSS class
Let us take a look at the Chrome DevTools, which you launch by selecting Hamburger button > More
Tools > Developer Tools from the browser header.

Debugging Scripts
The Sources panel lets you see and debug the JavaScript that are part of the inspected page. Standard
controls to pause, resume, and step through code are provided below the panel selection icons. A button
to force a pause at exceptions is located at the bottom of the window. Sources are visible in separate tabs
Clicking a tab opens the file navigator which displays all open scripts.

For more information, see the Chrome DevTools web page Debugging
JavaScript https://developer.chrome.com/devtools/docs/javascript-debugging

Inspecting the DOM Structure

The Elements panel lets us view structured information about the current page. The HTML markup
served on an initial page load is not necessarily what we will see in the Document Object Model (DOM)
tree. We can use the Elements panel for a variety of tasks that include:

 Inspecting the HTML & CSS of a web page

 Testing different layouts
 Live-editing CSS

305
For more information, see the Chrome DevTools web page Editing Styles and the DOM Introduction go
to https://developer.chrome.com/devtools/docs/dom-and-styles

306
 Creating Your Own Portal

Introduction
A portal is a specially-designed workspace for users that brings information together from diverse
sources in a uniform way. Portals generally begin with a login screen for users to access the
content. Designer Studio is a portal shipped for developers. Pega also provides the Case Manager
portal for managers and the Case Worker for users.
So, when a user logs in, what do they see? Be mindful and design each portal with a different look
and feel – distinguishing one from the other. Doing this can improve overall efficiency of the
organization, as each employee in a particular job would have access to the same portal.
At the end of this lesson, you should be able to:

 Design an end user portal by customizing the sections

 Create a new end user portal along with all the rules referenced in it
 Use dynamic containers to create work areas

307
Portal and its Components
A portal rule belongs to the user interface category and unlike other rules it does not apply to any class.
When defining a portal rule, we enter only the name and ruleset to which it is associated. Portals primarily
use two different UI rules – Harness rules for the content and Skin rules for styling. Portals can reference
the same skin used in the application rule. It is important that we do not change the fields in the
Configuration despite them appearing as dropdowns.

Like Portals, skin rules do not have an Applies To class but we need to pick the Applies To class name
for the harness that is being used. In most cases it is recommended that we use Data-Portal as the class
name since all the sections that we can see in Case Worker and Case Manager portals are defined in
Data-Portal class and we need to define the harness in the same class so we can reuse the sections.

Customizing portals can be done in one of the following three ways:

1. Modify the sections that are used in Case Manager or Case Worker portal.

2. Modify the harness used in Case Manager or Case Worker portal to include new sections or
screen layouts.
3. Create a new portal rule and a new harness rule. The harness can reference both new and
existing sections.
The skin rule that is used in the portal rule must be customized to ensure that the portals are responsive
when opened in a mobile device.

308
Harness Used in Portals
Portals reference a harness for content. If we are intending to use any of the shipped gadgets from
Pega7, the harness that is referenced in the portal rule must be defined in Data-Portal class. Most of the
newer gadgets are defined in @baseclass so we can save the harness in the application class layer as
well.

How do we design harnesses that are used in portals? Harness rules used in portals are a little
different in their construction from other harnesses that are used in work forms such as the Perform
and Confirm harnesses. Harness used in portals use screen layouts to group sections inside its
layout. When defining a new harness, the first step is to drag the screen layout from the layout
palette into the harness.

309
In the dialog, we need to select the type of screen layout. As we can see in the list we need to select a
harness based on the number of panels we want in the portal. For example is our portal going to require
just a header or will it need a header and footer along with a left and right navigation.

The harness is also referenced in the portal to render work areas, which we will look at next.

310
Dynamic Containers
Dynamic Container is an auto generated way of presenting the worklist and cases in runtime. Dynamic
Containers support presenting them in one of these three ways:

1. Single Document
2. Multiple Documents
3. Dynamic layouts

When creating a custom portal, the dynamic container is added in the section referenced in the center
panel because that is used as a work area by the users. The dynamic container is part of the layout group
in the designer canvas.

and after adding it we need to pick the rule that it can reference to. It can directly reference a section or a
harness. The mode field is used to select Single or Multi Document.

What is the difference between Single and Multi Document? In the case of Single documents, there is
only one active document used (for example, a case). When another case is created it closes the existing
document (removes the case from clipboard) and open the new case. Single Documents are useful in
cases when users work on one case at a time or access the work list to open cases. Single Documents
are pretty useful in keeping the application from overloading too much data and the performance is
always better. To add a single document, we just add the dynamic container outside the existing layout in
the section and then reference a section or harness.

Multi Document mode allows opening multiple documents at the same time. It is added the same way as
a single document. The system allows us to have a maximum of 16 simultaneous documents and by
default it sets 8.

311
Both these modes can reference section or harness for content. Typically we use sections when simpler
layouts are created and harnesses are when we want to build the whole screen. The default case worker
portal uses the work list section which displays the work list while the default case manager portal uses a
harness which displays the whole dashboard.

312
Dynamic Containers in Layouts
The third way of adding dynamic containers is placing it directly on a layout. This is normally used when
we are using it in one of the side panel or header panel and we want to refresh a small part of it and not
the whole panel.

In some cases dynamic containers are added in a tabbed layout so that multiple documents are opened
as new tabs.

We can also add the dynamic container inside a dynamic or a column layout. When we add a dynamic
container directly inside a layout it disables the default view and also renders the dynamic container only
in iFrames. We can select a section in the Purpose field and we can also use Multi Document mode.

313
Styling Portals
Portals can reference the application skin as well as other skins. It is extremely common to use a
separate skin for user portals. Providing this feature helps us to adapt different branding requirements for
customers based on regions, types, or any other distinguishing factor.

When it comes to styling the portals, the key component is to look for Screen layouts. As we can see we
can style each part of the screen layout (header, left, right, etc.) individually. Look in the presentation
group lessons to revise how to use mixins, images, icons and the color palette to style background and
borders.

314
Some parts such as Right pane also allow configuring response breakpoints, which ensure how the
content in the right pane appears on a tablet or another mobile device. As part of the response breakpoint
we can set the maximum width in pixels (suggesting at what point the responsive breakpoint is reached).
When the response breakpoint is reached, the navigation pane is hidden and can be accessed through
the use of an icon that appears in the screen header. The product uses a default image
(pyScreenNavigateIcon) which can be changed in the skin rule.

315
 Building Personalizable Dashboards

Introduction
The Dashboard provides useful information for business users in terms of business metrics, and a visual
display of these metrics to make the business processing understandable.

Providing the ability to personalize dashboards is extremely powerful as it enables users to see
information that is important to them. Users have the choice to customize their dashboard by selecting
from an inventory of widgets that can be plugged into their dashboards. In addition, personalizing your
dashboard does not require any involvement from the development team.

At the end of this lesson, you should be able to:

 Explain the business value in personalizing a dashboard

 Configure the portal and other associated rules to allow dashboard personalization
 Publishing the configured changes for other users

316
Need for Personalizing Dashboards
A portal rule controlling the contents of a screen is referenced in an access group. All users belonging to
that access group see the same portal. This is helpful in many cases when you want a team such as
developers to see the Designer Studio (which as we know is a portal for developers) and can familiarize
themselves with the placement of information. It also makes sense for Customer Service Representative
(CSRs) to use the same dashboard and they typically get a training manual on how to accept calls, how
to create a case, how to access work lists and so on.

However, personalizing your portal or the things you can see is also useful. Let us consider a manager
role, Manager A might be interested in seeing a specific report and would like that report on their
dashboard instead of running it on demand. A frontline manager might need reports to see what their
current team is working on while a midlevel executive might require a different set of reports. This can be
achieved by splitting them into two different access groups, however if they require the same set of
access roles and privileges then creating a different access group just for providing different reports on
the dashboard adds lot of maintenance. There might be multiple reporting hierarchies in an organization
and each manager will be interested in a different business metric. Creating access groups for each level
adds too much overhead and requires lot of maintenance.

Let us look at an example dashboard of a manager who is interested in seeing such business metrics.

This looks radically different from the default Case Manager portal and it also has the link at the top which
enable users to replace a report with another one. Let us look at how the user has configured it now.

317
Looking closer we see that the user has personalized the portal to display a different report (Progress
Chart instead of the Injury and Revenue snapshot) and has also changed how these reports are
displayed in terms of the space. This offers a great value for end users to customize their dashboard to
suit their immediate needs and they might also be able to easily change the layout without requiring any
additional development time. On top of that, there is also the ability for a user to publish his changes to
other users in his group who might be interested in getting their dashboard upgraded.

318
Terminologies
Let us try to define some terminologies that are used in the personalization of dashboards.

Dashboards – The first thing is of course is the dashboard. The dashboard is not the entire portal, it is a
piece of the UI that contains one or more widgets grouped into slots that are arranged based on a
template.

The definition uses other terminologies which require us to define them.

Widgets - A widget is a small re-usable UI component that provides an application specific function to a
user. Widgets can be added to the dashboard by placing them in the slots of a template. Pega 7 ships
with a wide variety of widgets which are a starting point and end users can add to them if necessary.

319
Templates - A template is an arrangement of Slots, each slot can have 0 or more widgets assigned to it.
Pega 7 ships a wide variety of templates which can be used as a starting point and end users can add to
them if necessary.

Now that we have defined these terminologies, let us see what an end user can do.

320
Personalizing a Dashboard
The Case Manager portal shipped as part of UI Kit has been configured to support personalization. When
we launch that portal we see an icon that allows us to personalize the dashboard.

Clicking the icon opens the dashboard for editing and now it shows slots, templates and widgets in the
dashboard.

The portal uses a Right Column template that has two slots and there are three widgets in slot 1 and two
widgets in slot 2.

Switch Template link – allows selecting from a group of shipped templates.

321
The slots are defined as part of the template, however users can add or delete widgets on the slots using
the Add widget link and delete icon respectively. Once changes are done they can save the template by
clicking Publish.

Clicking Add widgets opens up the Widget dialog from which end users can select.

322
The widgets are grouped based on categories. These are the rest of the widgets that are shipped in the
product.

323
Configuring Widgets
Some widgets allow additional configurations to be chosen by an end user. Let us see an example to and
learn how it works.

In most cases end users would like to add a custom chart or report to their dashboard. To include this we
need to add the Report widget into a slot. After adding the Report widget, we click the link to access the
widget options.

This opens the configuration options where we can select the report from its categories. In this example
we have selected a standard report.

324
Developer Setup Tasks
Now that we have seen how powerful the dashboard personalization is, let us take a step back to see
what the developers need to configure for enabling the personalization.

1. The first step is to include the pxDashboard section in the harness used in the portal. In the
Case Manager UI this harness is pyDashboard7 and is included as part of the section displaying
the main panel (pyPortalContent).

2. Include the additional css file py-dashboard-personalization in the Scripts and Styles tab of the
harness.

Ensure the user has the pxDashboard privilege usually set by security experts. Most of the
default security roles shipped in the product have this privilege.

325
 3. Launch the dashboard by clicking on the dashboard link which is loaded by default.

This references a menu control which we will learn about in detail in the navigation lesson group. The key
to remember is that it uses a data transform named pxUserDashboardPrepareDisplay while launching
the harness. So when customizing the portal we need to ensure this data transform is invoked. The
parameter named UserDashboardCategory can be left blank for all the new portal rules created.
CMDashboard is specific for rendering the Case Manager portal.

326
NOTE: The UserDashboardCategory is a data instance and it gets created automatically when users use
the system and publish their changes. Once these categories are added, we have options to create a
portal to use them directly using this parameter.

We can create a portal in which we can use multiple dashboards by passing different values for
UserDashboardCategory and users can either use a tab or menu to switch between dashboards.

327
Publishing the Dashboard
By default any operator with the pxDashboard privilege can customize their own dashboard and then click
the Publish button to apply their changes which will be applicable only for them.

Developers and mangers have a little more access and can publish for an entire workgroup. If we need to
modify the default behavior we can override the when rule pyUserDashboardCanPublishFor to add
additional options such as the operator’s access group. We can also modify the when rule to grant more
access for a specific user.

There is also a data transform pyUserDashboardLoadList which we can modify to make changes to the
default behavior.

328
 Module 10: Navigation

This lesson group includes the following lessons:

 Navigation Modes
 Using a Navigation Rule
 Creating Menus
 Embedding a Pega Application as a Gadget

329
 Navigation Modes

Introduction
Applications use multiple screens to gather data and one way of navigating between theses screens
occurs while users create, update and resolve a case. This navigation is controlled using the flow actions
which determine what should be presented when users submit a specific form. That said we do need to
provide navigation to different screens when performing an action or even before that when navigating to
different options after users log into the portal.

With that in context, as a UI designer we have to learn the different navigation options on screens and
then look at various options on forms.

At the end of this lesson, you should be able to:

 Understand which menus are used to present navigation choices in a screen

 Use a screen flow to present a long form into multiple screens
 List other options to present different dialogs or forms

330
Navigation Choices in Screens
What choices are available to us to use for navigation in screens? Below is the default Case Manager
portal and when looking at it we can see that it offers several navigation choices (highlighted below).

The header has two links ( the Create and Operator name links) which when clicked opens up a menu.
Clicking any of the options such as Bulk actions changes the content window.

Using LiveUI we can look at the configuration of these links, We will learn more about the configuration in
the Creating menus lesson.

Similarly, the left navigation pane shows a list that includes Dashboard, My Work, Calendar and Reports
which are rendered using a menu. We will learn about configuration of a menu control in the Creating a
menu lesson.

The Recent section also known as the Recents Explorer uses a set of API’s so you can open recently
worked cases from this gadget. This specification works only in the Recent gadget and we highly
recommended that the gadget be used as-is by including the section rule.

331
Navigation Choices in Forms
Long running forms have multiple issues, the top two being:

1. Usability – Users need to scroll down vertically losing the context of the selections they made
before.
2. Performance – Longer forms take a longer time to load all the fields that appear on the form.

This issue can be handled by splitting a long form into several screens using one of following methods:

1. Layout groups – enables us to split the form into separate layouts which allows the layout group
to be split into several tabs, menus or accordions. By splitting them we can handle the usability
issues, since users see only the active tab, accordion or the selected menu. We can enable the
defer load on tabs or accordions and handle the performance issue as well.
2. Screen flows- enable us to split a longer screen into multiple screens by using several flow
actions. Implementing a screen flow requires making changes directly in the flow rule.

Layout groups were covered in detail in the Using Layout groups lesson. Now let us see how we can
configure a screen flow. To include a screen flow, follow the steps below.

3. Create a new flow rule using the new rule dialog.

Then in the configuration dialog, click the link to view additional configuration options.

332
4. Select the option “Standard template for screen flows”. This option gives us access to the
template that we are using in the flow rule so that we can modify it as shown in step 5.

In the flow rule use the Flow Shapes icon to add Assignments. Each assignment corresponds to
one form that users view.

5. Modify the screen flow template. Since we have chosen the standard screen flow template, while
saving it we can have the option to select a specific harness style depending on how we want to
render the screen flow. To do this, open the start shape properties to modify the harness. There
are a few harness options applicable for screen flows. We can select whichever looks appropriate
for our application (more importantly for our end users). We will learn about this in a little bit, for
now let us pick one of these three choices.

o TabbedScreenFlow7
o TabbedNavigation7
o PerformScreenflow

333
 6. Save the flow rule. Now this rule has to be called from another flow rule. To do this we need to
add a subprocess flow shape from the Flow Shapes icon and then in the subprocess properties
we need to reference the flow name.

After the screen flow is added, users are presented with the Back and Next buttons enabling them to go
back and forth between screens. Screen flows are useful if forms are to be loaded one after another,
meaning we want users to process one form at a time and submit the form before proceeding to another
form. This is useful when we want sequential processing. Screen flows are also useful if the same single
user performs actions one after another as part of the case processing.

For example, in this screen flow we have three distinct forms to capture the data we need:

1. Personal Information – who it is for and other relevant data

2. Line Items – what items are needed for this request
3. Address Information – where we need to verify the shipping address and edit it if a change in the
address is needed

334
Selecting Harnesses
If the harness rule is set to “TabbedScreenFlow7,” the user interface shows the steps of the screen
flow as tabbed navigation. This user interface shows the current step of the screen flow highlighted
in blue and shows all the steps in the tab navigation. Users can navigate using the Back and Next
buttons or by clicking on a tab in the tab navigation. Users can also jump multiple steps forward or
backward by clicking on a tab in the tab navigation.

TreeNavigation7 presents the list horizontally and behaves the same as the TabbedScreenFlow7. If the
harness rule is set to “PerformScreenFlow” the user interface shows the steps of the screen flow as
bread crumbs. This user interface shows the current step of the screen flow and the previous steps in the
horizontal bread crumb display. This harness option of the UI display does not show the future steps.
Users can navigate using the Back and Next buttons to go backward and forward. With the bread crumbs,
they can only go backward, not forward. So, if users click on a bread crumb in the navigation, they can
only jump multiple steps backwards.

The business can decide which user interface option they want to present to their users. There is no
difference between these three, as far as functionality, except in the “Perform Screen Flow,” where
users cannot jump multiple steps forward.

335
Navigation Using Controls
Controls in general can be used to present dialogs or screens in modal or overlay. To do this we require
an action control and in the action event dialog we configure it to launch the local action in either a modal
or overlay.

Styling the Modal and Overlay Dialogs

Modal and overlay dialogs can be styled using the skin rule with one of the standard formats or we can
create a custom format similar to other components we have seen in the presentation lesson group.

When using menus or overlays we have the option to set how modal or overlay appear and close using
one of the shipped animation styles.

336
Since the overlay dialog does not display on top of the current screen, it also allows us to choose if we
want to align the overlay to be centered or if we should allow users to click away from the overlay without
performing any action.

Since modal and overlay dialogs reference flow actions they use the action buttons (Submit and Cancel
by default). We can modify the button labels in the flow action rule and if required we can even disable
them (if we are using overlays).

In the next lesson we will learn about the navigation rule and then in the lesson following that we will learn
about how to use menus. Menus can be added in the forms and can be a navigation choice if required.
We will look at some examples in the lessons that follow.

337
 Using a Navigation Rule

Introduction

Pega offers a complete UI building solution - From the outermost portal, to layouts, to individual controls
to navigation and everything in between. Navigation as we saw in the previous lessons is implemented in
various ways and the navigation rule plays a key role. The Navigation rule is useful in presenting a
hierarchical relationship of various objects especially when each object is clickable to present an action.
Let us look at an example to better understand the hierarchical relationship. When working on a web
page it is common to have various screens and users need the ability to move from one screen to another
by clicking through a menu. When clicking a menu it opens up a list of items and when the user clicks a
specific item it opens up another sub list and so on.

Let us see how we can use a navigation rule to present this hierarchical relationship.

At the end of this lesson, you should be able to:

 Describe the Navigation rule

 Configure Navigation rule

338
Examples of Navigation Rule
Navigation is a rule type belonging to the user interface category, however unlike other user interface
rules it does not involve building CSS or HTML screens. Unlike other UI rules, it is used to build a multi-
level XML document.

So, where can we use an XML document in a Pega 7 application? The XML document is useful to
present a parent child relationship. Let us look at an example where this might be useful. This is part of
how we define the Amazon product catalog (shown below) where the product categories and product sub
category relationship helps in classifying and grouping products.

Now, let us look at a similar example in Pega 7. The Designer Studio landing page is structured based on
the Navigation rule. Clicking through the tree starting with the User Interface menu item, we can see that
there are three levels in this relationship. On the User Interface landing page menu, clicking any of the
next level items opens the landing page but not the localization tools. Clicking on the localization tools
displays the third level where we can view the various options such as running the localization wizard or
viewing the translations that are in progress or setting the locale.

339
The other example where we can see the Navigation rule is when we present a context menu. Context
menu refers to the menu that appears when right-clicking on a specific UI element such as the My Cases
gadget in the Case Manager Portal.

What is common to both of these examples?

1. It presents a menu with menu items displaying the parent child relationship.
2. Clicking a menu item performs a specific action – for example, Clicking Cut and then Paste we
can move the layout to a different place. And clicking the User Interface opens the child items and
clicking Translate to New Language opens the localization wizard.

340
Configuring a Navigation Rule
We saw a couple of examples where the Navigation rule is used. Now let us learn how to create a
Navigation rule to display the UI landing page that we saw earlier. Like other UI rules, a navigation rule
allows us to create a multi-level XML document in an auto-generated fashion.

The rule form allows us to add items or child nodes using the tool bar. To add a new item we use one of
the Add links.

341
Once added we have to configure two parts. – In the General Tab, we need to select the type.

 Item is the most commonly used type to add a menu item.

 Item List is used when we need to present the menu item from a page list.
 Reference is used to reference another Navigation rule.
 Separator is used to add a separator line.
 Selected Item is used in context menus.

The second part that we will configure is in the Actions tab. We need to define an action set, this is similar
to what we have seen in controls except the event is hard coded to the click. In essence, we are just
specifying the action that needs to run on the click.

When we click Add an action we are presented with a dialog similar dialog to what we saw while
configuring actions on controls. It lists the most common actions that we normally specify on the
navigation rule as an action.

342
To see other actions we click the All actions link to open up the menu.

There is also the ability to configure selections in the Presentation tab if required. When choosing
Checkmark we see a checkmark that appears next to the selected item. Group selection allows us to
select multiple items belonging to one group.

Custom is used to reference an activity rule for the action. When custom is selected, other choices
disappear and all the processing is defined in the activity rule. We do not recommend that you use this
process.

343
Now that we have seen how these are defined, let us go back to the User Interface menu rule to see
couple of examples.

344
Configuring a Navigation Rule to Present the Context Menu
Let us go back to the example where we saw the context menu presented on the Case Manager portal.

When we look at the underlying Navigation rule we can see that it references a Navigation rule named
pyBaseNavigation.

When looking at that rule we see that it also has additional items than what we saw in runtime. They all
have visibility conditions and will appear as and when the conditions are satisfied. Navigation rules can be
configured to apply multiple actions as we see in this example. When the user clicks Complete it opens a
local action and submission of that will refresh another section and then clears the dirtyState flag. Run
Script option is useful to invoke custom JavaScript actions defined in the JS file.

Conclusion
In this lesson, we learned that where a Navigation rule can be used and how to define a Navigation rule.
Take a moment and look at other instances of the Navigation rule in the application to see how they are
defined. To see how the Navigation rule can be displayed as a menu or a context menu we require using
a special control named menu. We will learn about that in the next lesson.

345
 Creating Menus

Introduction
Navigation as we saw in the previous lessons is defined using the Navigation rule and it can be presented
to users through the use of a menu. Menus are useful as we can present information specific to the
context. When clicking a menu it opens up a list of items that is applicable to that node. Let us see how
we can use a menu control to reference the navigation rule.

At the end of this lesson, you should be able to:

 Configuring a menu control to reference a navigation rule

 Configure the context menu

346
Configuring a Menu Control
The menu control is part of the Advanced palette and can be added into the layout.

After adding the menu, we have to reference a Navigation rule for its content.

347
We can style the menu in the skin rule by using formats. We can use one of the shipped formats or create
additional formats. In addition, the menu control can be styled to display either vertically or horizontally.

In the skin rule, menus can be configured using the three tabs below:

1. Menu bar – The selections we make here affect how the menu bar looks.
2. Menu Panel – The selections we make here affect the item box that appears when users click on
the menu.

3. Menu Items – The selections we make here affect the list of menu items that appear.

Note: Review the Presentation lesson group to learn more about configuring the mixins and mixin
overrides.

Apart from configuring the text, borders and background for inactive and active states, we can also
configure a few other things that apply for mobile devices where screen space is limited.

Under Vertical Menus, the “Show sub-menu as inline replace menu” when enabled lets the sub-menu
replace the menu currently on the screen when the sub-menu appears and a back navigation icon is
available on the screen to return to the menu. Under that Horizontal Menu, the setting width can be sized
to fit the screen size.

348
We can select Add responsive breakpoint to render menus on mobile devices. The menu is then available
when users click on the icon.

Under Full Screen Menus, we can select “Display the menu as full screen menu.” On mobile devices this
takes up the whole space.

349
Presenting a Context Menu
Using the Context menu is the second way to render a Navigation rule on the UI. This is useful to render
a menu when users click on a specific context.

Let us look at a few examples where we can plug-in a context menu.

1. Grids: We can set one of the click actions in the grid item to invoke a menu. Let us look at an
example, in the Case Manager portal we can see the “My Cases” list presents a menu on the
right click of an item in the list.

When we look at the underlying section, we can see the following configuration.

The menu is configured to render on the right-click action. The Navigation rule is referenced in
the Content field. The other fields let us set the presentation of the menu including how the sub
menus are aligned. The Load behavior field controls when the menu items are refreshed which
we will look at it in the next part.

350
2. Controls: We can set one of the events to invoke a menu in a similar fashion. We can add an
action set on the actionable control such as a button, icon or a link which can reference a menu.
Though it allows configuring a menu, we need to be judicious in using it for any user input control
as the action might deter from entering or making selections. In the User screen, we can see a
menu popping out when clicking the username link that appears on the portal.

When we look at the underlying section rule we can see that it uses the link control and the menu
is referenced on the click action. The configuration of the menu is similar to what we saw earlier.

351
Conclusion
Menus are a powerful navigation feature but can be used in other scenarios as well. One example being
the layout group can be rendered using a menu. Menus can be styled in the skin rule and can be applied
on all places where it is added.

Lastly menus can also be configured to render the menu items only on demand. The load behavior field
that we saw discussed previously can be configured to make sure the menu items are not refreshed
unless necessary.

1. At screen load – As the name suggests, menu is rendered only on load and for every
subsequent click it takes it from memory and does not go back to the server unless the containing
section is refreshed. This is the preferred load behavior since it renders the menu quickly.
2. On first use – This configuration allows the menu to be rendered only when it is requested at
least once. This might cause some bad user experiences since it might take a longer time when
the menu is accessed for the first time. However, it renders it instantly on all subsequent
requests. We might require this behavior for applications, but alternatively we can use “At screen
load” instead and put the menu in a defer loaded section. It will take longer to load the screen,
but the menu experience is better.
3. Refresh on display – This is the default behavior and causes the menu to be reloaded from
server every time. This option should only be used when the contents of the menu is changed
between the loads of menu and the refresh of the contained section.

352
 Embedding a Pega Application as a Gadget

Introduction
A mash up is a term used for Web applications that merge data and content from multiple sources and
presents them in a common user interface. Pegasystems Internet Application Composer (IAC)
implements a Pega application as a gadget, which can be used in a user interface framework that is
already. We use IAC to build Pega composite Web applications that we can embed directly and securely
on company Web pages as a mashup.

At the end of this lesson, you should be able to:

• Describe the Internet Application Composer (IAC)

• Describe the terminology used in IAC mashup applications

• Configure a Pega application for use in a mashup

• Generate gadget code for a case in Designer Studio

• Describe how we can customize the gadget

353
What is IAC?
Typically, we access a Pega application on the Web using composite portals, which include the case
manager, case worker, or Designer Studio. The Pega user interface displays in the entire browser
window. The portal rules do not require integration with an external system.

IAC, on the other hand, allows us to embed the Pega application as a mash up by embedding a
composite application as a gadget in an existing Web application.

IAC is designed to work with the all standard Pega harnesses and sections. UI customization is not
necessary. In other words, an existing Pega application can be embedded as a mash up without making
any modifications.

The example below shows a gadget in the marked area that presents a screen flow in an auto insurance
quote application within the company Web page. The process was built using standard Pega UI
elements.

354
IAC leverages all the different authentication and authorization methods supported in Pega. Standard IAC
authentication activities in the PegaRULES ruleset can be customized to integrate with the third party
authentication implemented in the external Web application. IAC is designed to work seamlessly in any
Java or .NET Web application.

355
IAC Architecture in a Web Application
There are three main components in IAC; the Pega Gadget Manager, the Pega Instance, and the Pega
Composite Gateway. Let us look at all of them now.

Pega Gadget Manager — A JavaScript file PegaInternetApplicationComposer.js file, that contains the
scripts to launch the Pega composite application in a Web application as a gadget on the web page.

We need to perform two tasks when setting up the Gadget Manager:

1. Add configuration properties such as the URL of the servlet, the system ID of the Pega
server, the name of the application, and so on.
2. Create an HTML DIV element for each Pega Gadget, the gadget should indicate the Pega
action, action attributes and the Gadget Manager attributes.

We can use the Gateway Configuration Console for both these tasks. We can also use the
Generate Mashup Code option in the Case Explorer to generate the HTML DIV element for
the case.

Pega instance —The Pega server containing the application that handles the requests coming from the
IAC users.

Pega Composite Gateway — A servlet that is used to proxy the HTTP communication between the
Gadget Manager and the web page that displays, “This servlet (prgateway.war) is included in the Pega
installation bundle.” The system administrator must deploy prgateway in the Web server.

356
The gateway servlet and the Web application containing the Gadget Manager must be co-located in the
same domain. The Pega application is deployed on another server. Note, that if the Pega instance exists
in a different domain then we can only access it using a gateway servlet.

357
Developing Pega Composite Applications
A Pega composite application is an application that is embedded on company Web pages as a gadget.
However, before we can embed the application, we must build it. And as we build it, we need to preview
it.

Therefore, developing the composite application requires that we develop the application and build the
page that displays it concurrently. We iterate between application development and page development
because we must use a gadget to preview the application we are building to verify that it works.

During development, keep in mind the following guidelines.

Validate Custom Harnesses and Sections

Pega gadgets invoke a specific Pega action, which can show the worklist, create a new case, or get the
next case using the Get Most Urgent logic. In most of these cases it launches a harness rule. All standard
auto-generated harnesses (such as New and Perform), sections, and flow actions can be rendered on all
supported browsers as listed in the Pega platform support guide for your version of Pega.

Apply Styles Using Skin Rules

Because companies give access to their Web applications, the Pega application should match your
company’s styles. To enforce consistency, compatibility, and reusability, use skin rules to create these
styles; do not directly embed your CSS (Cascading Style Sheets) in your Pega application.

Even though the portal rules themselves are not used to display your composite application, the skin rules
associated with those portal rules are. When users of your composite application are identified, the name
of the portal rule assigned to their access groups is available from the clipboard tool. The system
identifies the skin rule associated with the portal rule. The HTML streamed back to the gadget uses the
styles specified by the skin rule.

For best performance results, do not use images in your harnesses.

Choose an Authentication Mode

The Pega application needs to authenticate users and map them to access groups. However, if users are
not presented with a login page; they might be logged into the Web application and the gadget passes the
user credentials. We need to match the values stored internally to validate the authenticity and then give
them access. All authentication modes such as SAML web SSO, LDAP, or third party authentication
methods can be extended to IAC. Pega includes standard IAC-specific authentication and timeout
activities, which can be customized.

Composite Application Restrictions

You should be familiar with the following composite application restrictions:

 The application can have only one work pool associated with it.
 Access groups always reference only one application. If additional applications are needed, we
typically assign operators to multiple access groups. Standard composite portals support
switching among access groups. However, because a gadget can display only one application,
IAC requires that we use an additional gadget for each application. In short, a gadget can display
only one application. Note that there are additional Gadget Manager API capabilities available we
can use so that multiple gadgets can communicate with each other.
 The worklist can display assignments belonging to only one application. In cases where there are
multiple applications, there must be multiple gadgets.

358
Unit Test the Composite Applications
The first step is to confirm that the Pega gadget code written in the DIV tag is correct. We can confirm this
by saving the DIV tags in an HTML stream rule in Pega. We can then create a Portal rule of Type
Custom. The Portal rule can reference an activity rule and in the activity rule, we can use the Show-HTML
method to display the HTML rule. We can confirm this by opening the portal rule. It is a best practice to
use the Gateway Console or the Create Mashup Code option to create the gadget and preview it to
minimize user errors.

After confirming the HTML stream we can then test it by saving the HTML code as an HTML page.
Remember, if the Web page and the Pega instance exist in the same domain, there is no need for
Gateway servlet.

Follow the Same-Origin Policy

One other important requirement for IAC deployment is to make sure that the same-origin policy is
followed. This is a security rule enforced by all browsers to guard against cross-site scripting attacks. This
rule enforces that the protocol (http), host name and port number matches for the external Web page
containing the gadget html and the Pega server. If the Pega server is located in a different domain then
we must install the gateway servlet and make sure that the servlet and the gadget html are co-located.

359
Creating Gadget Code in Designer Studio
The case flow is a common requirement for embedding Pega 7 content in another application's web page.
We can create a case type IAC gadget code from the Case Explorer in Designer Studio as described
below.

1. In the Actions menu, select Generate mashup code.

A new modal dialog displays where we enter the URL of the external application that we
want to target for our mashup. By default, the URL is the current system.

We can edit the URL directly in this text area. For information about installing or deploying a
gateway servlet, click the deployed IAC gateway servlet link which opens the PDN article
Configuring Internet Application Composer (IAC).
2. Click Generate code to display the HTML code required to embed the application in your
web page. Copy and paste the HTML into your external web page to display the embedded
Pega case type. We can modify the default settings after we paste the code onto the page.

360
Configuring the Gadget
We can configure the gadget to take advantage of the Gadget Manager API, which provides a wide array
of functions, properties, attributes, Java script actions, and events that we can use to configure
presentation, response behavior, infrastructure, and intra-gadget communication. Examples include:

 The default action PegaA attribute called createNewWork creates a new work object using a
specified flow when the gadget is loaded on a web page.
 The event-based attribute called PegaE_OnLoad so that the Pega content is positioned at the
top-left of the screen when the content loads. The code is shown below.

We can also use px or % settings in the style tag to position the gadget on the webpage. For example, if
we want to use less than the entire width of the containing HTML element, we would modify the width
style; for example, style=”width:50%”. Similarly, we would use a margin style to position the gadget’s
vertical placement; for example, if width is 50%, we would set style=”margin-left:25%” to center the
gadget on the screen. To maintain responsive behavior, we would not use fixed (px) widths or margins.
On the other hand, we could use a fixed height such as “height=600px” to present the gadget in correct
proportions on the webpage. Below is an example of how we might use the style settings.

361
 Module 11: Mobility

This lesson group includes the following lessons:

 Designing a Mobile Application

 Mobile Specific Controls and Behaviors

362
 Designing a Mobile Application

Introduction
With the ever-increasing popularity and wider usage of smartphones, tablets, phablets and other such
mobile devices, enterprises now require that their applications be accessible on all of these devices. This
requires many developers to have to write code and then test applications in various screen resolutions to
be certain that their applications work on the different devices. Mobile Application development requires
that specific code to be written to ensure that the application works on any device (Android or iOS).

What if we said Pega 7 helps in building an application once and running it anywhere? How is this
feasible? How does the application adjust itself to present a user interface tailored to the device?

At the end of this lesson, you should be able to:

 Explain the Concept of a Responsive UI

 Configure a Responsive UI
 Explain the Concept of an Adaptive UI
 Configure an Adaptive UI

 Explain UI Principles for Mobile Ready Applications

363
The Concept of a Responsive User Interface
A responsive user interface is aimed at optimizing a single design or layout across a continual spectrum
of devices and sizes. In other words making it easy to read and navigate with a minimum of resizing,
planning, and scrolling. Let us start by looking at an example. The Case Manager portal consists of three
areas: a main area in the middle and sidebars on the left and right.

When we reduce the size of the screen the left sidebar collapses.

We can uncollapse the sidebar using the icon highlighted in the toolbar below.

364
If we further reduce the width some of the columns (urgency and owner) in the work list are dropped and
the right sidebar is pushed below the main layout.

Hence, the UI adjusts itself to the screen size. Responsiveness is configured mainly in the skin rule by
defining one or more response breakpoints. Before we have a look at the configuration, it is important to
understand the standards mode.

Standards Mode
Modern browsers comply with the open standards set by W3C, the international community created to
standardize web technology. Web applications use a combination of HTML, scripting and CSS.
Applications that are “standards-compliant” are using standard W3C code and thus will behave
consistently in most modern browsers. Older browsers may not understand current standards and
therefore will have trouble rendering modern code.

The Internet Explorer browser (versions 8-11) can also translate code as if it were displaying on Internet
Explorer 5, in other words using non-standards. In this state Internet Explorer is in “Quirks mode”.

Pega 7 allows applications to be developed using either the modern standards or the older “quirks” code.
Pega 7 applications must use “standards mode” to take advantage of modern features, such as dynamic
layouts, column layouts, screen layouts and repeating dynamic layouts.

Standards mode is enabled by default. The settings can be found in the following places.

365
In the application rule there is a flag (Render in HTML5) listed under the Presentation section on the
Definition tab. When checked standards mode is enabled.

In the harness rule on the Advanced tab we select Inherit from application rule for the document type and
the application renders in standards mode.

If our application was built prior to Pega 7, we can upgrade to standards mode by using the HTML5
readiness gadget. Refer to the PDN article (Upgrading an application to render in HTML5 Document Type
- Node ID 22341) available from the related content area. It provides step-by-step instructions on how to
upgrade to HTML5.

When using Internet Explorer (IE) as the browser, we need to disable compatibility view for the standards
mode to work.

Using standards mode, we can add newer layout types such as dynamic layouts, column layouts and
repeating dynamic layouts. The newer layout types use the <DIV> tag instead of the <TABLE> tag which
makes it much more flexible to resize the information based on the screen resolution.

366
Configuring Responsiveness in Portals
Designing applications requires careful planning of the user workspaces especially when users access
applications on a mobile device. The image below shows the Case Manager portal accessed using a
desktop browser.

The images below shows the Case Manager portal accessed on a mobile device. The items in the left
sidebar have been rolled over into a collapsible menu, shown in the header.

How do we implement this in Pega? For sidebars (left and right), responsiveness must be set so that the
columns do not appear and get rolled into a navigation menu when accessed on a mobile device.

The Case Manager portal is using a screen layout with a header, left sidebar, and center areas.

367
When the response breakpoint is reached (in this case when the screen width shrinks to below 1279
pixels) it gets rolled over to the header as an icon. We can customize this and change the width at which
it rolls over to that setting, and the icon that is used to access the pane.

368
Configuring Responsiveness in Dynamic and Column Layouts
In the dynamic layout configuration we can transform the layout to a different format or hide it at a
breakpoint. So for instance, an inline grid triple styled layout becomes stacked at 480 pixels which means
any device accessing that screen width will render the layout in a stacked format.

This is how it would look before the responsive breakpoint is reached.

This is how it looks after the breakpoint is reached, in this case, when the screen width is less than 480
pixels.

369
Floats
Another powerful feature of dynamic layouts relevant to building a responsive UI is that the layout can be
floated to the left or right. When float is selected the layouts can be aligned to the left or to the right. In the
presentation tab there are other fields you must review that are very important when using floats. In this
example, these are all enabled. However, by default only Self-Clear is enabled.

Let us look at the options:

 Set layout width to auto – This flag allows layouts to use only the width that it requires.
 Self-Clear – This field is enabled by default and is used to account for the height of floated
layouts.
 Clear floated layouts – This field clears other floated layouts so that they do not appear in the
same line.
The Designer Studio header bar uses two layouts, one floating left and one floating to the right.

The section rending the header bar looks like this.

370
So, how do they appear in the same line? Besides the float setting we enabled, the set layout width to
auto field which makes sure the layout takes up only the space it requires. This helps in putting both the
layouts in one single line. Notice the other fields are disabled. Self-clear does not apply since there is no
other layout in the section other than these two layouts. If the Clear floated layouts flag is enabled then
both layouts float in two separate rows.

Column Layouts
When using column layouts the main content can be configured to appear at the top while the sidebars
get rolled down below it.

371
The center area in the Case Manager portal is configured this way. The right sidebar rolls down below the
main area when the breakpoint is reached.

372
Configure Responsiveness in Layout Groups
In addition to setting responsive breakpoints, layouts can be made responsive using layout groups. A
Layout group is a way to group different layouts such as dynamic layouts, column layouts, repeating
dynamic layouts and present them together. A Layout group can also include another layout group.

How is a layout group presented in user interfaces? The following four formats are supported by default.

Tab

Accordion

Stacked

Menu

373
Breakpoint definitions allow a layout group to be rendered in Tabbed format on a laptop, in Accordion on
a tablet and as a menu on a Mobile Phone. Layout groups require that the applications be rendered via
the HTML5 Document Type (standards mode).

374
Configuring Responsiveness in Grids
Grids are one layout where we need to configure responsiveness in the skin but also on the actual grid.
First we need to enable Responsiveness on the Presentation tab.

We then need to use the properties panel of the column to set the Importance flag as ‘Primary’,
‘Secondary’ or ‘Other’.

The skin rule offers three actions on a breakpoint:

 Drop columns with importance ‘other’

 Transform to list
 Hide grid

375
In our case there are two breakpoints defined. The first one is at 1024 pixels and hides the ‘Other’
columns and the second one is at 768 pixels and transforms the grid to a list.

Shown below is the grid before any responsive breakpoint is reached.

When the first breakpoint is reached, this grid removes the fields that are marked as ‘Other’, in this case it
is the Category and the Unit Price.

When the screen size reaches the second breakpoint it is transformed to a list. The primary column
appears as header while the secondary columns appear below the header. In our case the Product
column is marked primary and appears as the header with the Quantity and Price which are marked as
secondary below. The skin rule can be configured to show how the primary and secondary cells are
styled.

376
The Concept of an Adaptive User Interface
An adaptive UI, also known as AUI, is a user interface that changes its layout and elements based on the
needs of the user or context. The advantage of an adaptive UI is the ability to conform to a user’s needs,
which creates less confusion and provides ease of access throughout an application. Let us have a look
at an example.

The Case Worker and Case Manager portals come with a mobile preview option in the operator menu.

We can select the device we want to view the portal on. Here we have selected tablet.

The same screen looks like this on a phone.

377
We can see that some of the gadgets, such as Pega Pulse, Team members, and Workbaskets are not
available on the mobile version. On the phone even the stages gadget has been removed and only the
work list displays.

As we can see an adaptive design changes to fit a predetermined set of screen and device sizes. A
responsive design on the other hand is flexible across a continual spectrum of devices and sizes.

378
Configure an Adaptive User Interface
There are a set of standard when rules available for configuring an adaptive UI.

1. pyIsAndroid – returns true if an Android device

2. pyIsIOS – returns true if an iOS device
3. pzIsPegaMobileSDK – returns true if Pega mobile SDK is used

4. pyIsTablet – returns true if a tablet

5. pyIsMicrosoftMobile – returns true if a Microsoft device
6. pyIsMobile – returns true if a mobile device
7. pzIsHybridClient – returns true if a Pega custom mobile app

Here is the standard case assets section which uses the pyIsMobile when rule to hide the case tools
section on mobile devices.

It is also possible to use circumstancing when configuring an adaptive UI. Circumstancing is a way of
creating specialized copies of rules based on the evaluation of a condition.

379
For example, we could circumstance on a property called DeviceType. This ensures that rules marked for
the device type are selected at runtime.

Circumstancing is not covered in this course, refer to Pega 7 help for more details.

380
UI Readiness for Mobile Application
Mobile applications follow the same Core UI principles. However, the designer and developer of the
application must be aware that the user interface may be accessed on a mobile device. Follow the
guidelines below when building applications that are mobile ready.

1. Keep it simple – Highlight the most important part of the screen by putting it front and
center. If there is supporting information, or less critical information that needs to be
displayed consider hiding it unless the user asks for the information. This can be done by
putting it under the most important content, or using progressive disclosure either by using
collapsible sections, menus or some other paradigm.

2. Enable Responsiveness – This ensures that the UI screens appear correctly on a mobile
device and make the best of the available screen space. This way we can design a UI that has
fields spread across three columns on a Desktop, spread across two columns on a tablet in
portrait mode and for a phone the layout can either be in landscape mode and or stacked
into a single column when the person is on the phone.
3. Setting widths in Percent (%) - Avoid using pixels on layout formats, using percentages
enables the layout to automatically adjust for different screen resolutions. Using a fixed
width has the risk of injecting a horizontal scrollbars on a smaller device.
4. User Controls - Pega 7 comes with a wide repository of user controls, but we should use
them judiciously. Always use out of the box auto-generated’ controls. These are designed to
work on all browsers and devices. They also have mobile specific configurations. For
example, we can configure a date control to have a native rendering when on a mobile
device. Set the data type of the property carefully, so that the correct keypad choice appears
(number, alphabetic, and so on.)
5. User Actions – Certain events are configured to occur on a specific user action, such as
navigating a menu using the mouse movements which is harder to do on mobile devices,
but can be done by redesigning the menus to work on taps. Use a Collapsible navigation
menu which makes this easier.

6. Design the application with ‘Tap’ in mind – Buttons are easy to tap on, but not links. It is
easier to click using a mouse than to tap on a high pixel count touch screen. Ensure that
actionable components are easy to tap. We can use layout level events and actions to help
with that.
7. Designing Layouts – A layout group is another key feature that helps when displaying
layouts in different paradigms such as tabs, accordions or stacked layouts depending on the
screen size. Layout groups are formatted in the skin rule using response breakpoints to
switch to a specific header format based on the resolution size.
8. Grids – Grids do not work well on a mobile device when there are more than a couple of
columns. If you have a grid with a lot of columns, identify the columns that are not so
important. Then identify the most important columns. Mark the columns in the grid as
primary, secondary and other. The grid layout then uses this information to adjust on a
mobile device using responsive specifications.
9. Repeating Dynamic Layout instead of Grids – Grids are great for displaying columnar
data. If you are not showing columnar data but merely showing a list, use a repeating
dynamic layout instead. It is a lot more flexible than a grid, especially on a mobile device.
10. Sourcing Controls and Grids – Always use data pages as a data source regardless of
whether the UI is going to be used on a mobile device. This is absolutely required if we are

381
 designing applications to work on a mobile devices when the device is not connected to a
network.
11. Testing – There is no alternative to testing the application UI on a mobile device. Do not use
simulators to test it. This ensures that our application performs well, provides the right
experience and works and behaves as we would expect from a mobile application.

382
 Mobile Specific Controls and Behaviors

Introduction
It is becoming increasingly important for applications to offer a seamless user experience when accessed
from different devices. Pega 7 includes many features that enable us to build a seamless user
experience. In this lesson, we will look at how certain controls that are common in mobile applications can
be configured to enrich the user experience on mobile devices.

At the end of this lesson, you should be able to:

 Configure the Address Map, Signature Capture and Attach Content Controls

 Configure an Application for a Mobile Experience

383
The Address Map Control
The Address Map control allows us to view and interact with location points in Google Maps from within
both desktop and mobile applications. To display locations correctly on a map, geolocation must be active
for your web browser or mobile device.

Obtaining a Google API Key

For the Address Map control to work correctly we need to obtain a Google API key. In a production
environment, the recommendation is to use an enterprise key, since this allows for a greater number of
geo-coding hits per IP each day.

Perform the following steps to obtain the Google API key:

1. Access the Google Developer Console at https://console.developers.google.com and log in to

your account.
2. Select a project or create a new one.
3. Locate the APIs section and enable Google Maps JavaScript API.
4. Locate the Credentials section and create a new browser key to use for Public API access.
The previous steps are accurate as of the publication of this lesson. Refer to the official Google
Developer documentation for Obtaining an API Key
at https://developers.google.com/maps/documentation/javascript/tutorial#api_key for additional
assistance with this process.

Once generated, enter the key in the Dynamic System Setting uiengine/map/googleapikey.

Adding the Address Map Control

In Designer Studio, add the control to a layout by selecting Advanced > Address Map.

384
Adding this control displays a static image of a map to indicate the location of the control.

Displaying Locations on the Map

In the Cell Properties window, the General tab displays various configuration settings for how the map is
displayed.

If the Show User Location check box is selected the user’s current geographical location is depicted by
a blue marker on the map. The location can not be changed manually. The location only changes when
the user physically moves.

385
Use the Starting Lat, Long to set a starting view of the map. It is possible to hardcode the coordinates by
enclosing them within double quotes, such as “42.366200, -71.076936”, or specify a property, such as
.HomeAddress, containing the coordinates. This does not put a marker on the map but just zooms in on
the coordinates given.

The starting coordinates are not always used, since the map initially zooms in/out as it attempts to fit all
markers and the user’s current location in the same window. This field is also ignored if the Type in the
Markers Source section is specified.

Selecting Property in the Type menu of the Marker Source section allows us to specify a location in the
Address property field. This can be an address in human readable format or as latitude/longitude
coordinates. The address can either be hardcoded in the field as is done here or provided through a
property reference.

386
Address locations are displayed with red marker pins.

We can select Allow marker repositioning to change the address value if we want the user to update
the current location dy draggging the map marker to a new position. The value bound to the Address
property field is automatically updated, or if the new location on the map does not correspond to a human
readable address, the property is filled with the latitude/longitude coordinates.

We can use the Report lat long in property field to specify a property to track the latitude/longitude
coordinates. Select Report incorrect address to display an error message when the address at the new
location cannot be found.The message is specified in the Error Message field.

Sometimes we want to display several markers on the map. In such cases a list-based source is required.

The following options are available:

 Property with List defined on property

 Data Page

 Clipboard Page/Group
 Report Definition

387
In each of the above option case we need to specify the Property for location. For example, this data
page holds nearby restaurants. The location is defined in the address field.

The Marker Information Section allows us to specify a section displayed in a popup when the user
clicks or tap the red marker pin on the map.

For Data Pages, Clipboard Pages, and Report Definitions, the Markers Source section runs in the context
of each row.

Customizing Size and Icons

In the Cell Properties windows, the Presentation tab allows you to select a radio button that sets the
height of the map either automatically or with a custom setting. The custom setting as shown below
allows you to specify a number as either px, em, or %. Note that % is not supported in dynamic layouts
since they do not have any height configured.

The Address Map control icons can be customized to make them consistent with the look and feel of the
application. The marker icons can be changed globally by updating the following binary files.

388
In some situations it may be useful to change the marker icons. For example, to show an airport location
with an airport icon and a coffee shop location with a cup icon on the same map displayed in the
application. We can do that by sourcing the address map control from a report definition.

The following properties in the report definition affect how and where map markers are displayed.

Type Property Name Default Value Comment

Icon URL MarkerImage Google maps default This may be an external URL or a relative
image URL pointing to a Rule-File-Binary.

Icon size MarkerImageSize 32,32 Standard icons (like the one in URL below)
come in 32X32 size. Set this property to
accommodate bigger icons or to control the
size.

Icon origin MarkerImageOrigin 0,0 If the icon is part of sprite, set this value to
get the correct image.

Icon anchor MarkerImageAnchor 16,32 The point where the icon’s hotspot should
be located.

389
The Signature Capture Control
We can use the Signature Capture control to capture a user signature, either through a mouse input or
through a touch interaction on a mobile device. Interacting with this control in an application occurs by
displaying a field inline where a signature can be scribbled. The control supports offline mode.

When the user clicks Accept the entered signature is saved as an attachment in the case. The control
must be used in the context of a case. Entering and accepting a signature can be repeated as many
times as necessary, but only the last signature is saved as an attachment when submitting an
assignment.

When the user clicks Clear, the current signature is wiped out so that a new one can be entered in the
field. If a signature has been saved as an attachment and then the user clears the erased signature, it will
still be availabe as an attachment.

A signature is automatically cleared when the control is resized, for example when changing the
orientation of a mobile device.

Adding the Signature Control

In Designer Studio, add the control to a layout by selecting Advanced > Signature Capture.

390
In the Cell Properties window, the General tab displays various configuration settings for how the map is
displayed. Specify the name of the signature attachment in the Signature name field and the attachment
category in the Category field.

The control is responsive and will automatically use 100% of the width when rendered on a mobile
device. It is possible to define the Min height and Max width in the Presentation tab.

Create Custom Accept/Clear Buttons

We can leverage a click action with a JavaScript event to add our own custom icons for accept and clear.
Follow the instructions below.

1. Select Hide default Accept/Clear actions on the Presentation tab.

2. Add two icons, for example within a section containing the Signature Control, representing
the accept and reject actions.
3. Add an action of the Run Script type for each icon.
4. Enter the following JavaScript function names in double quotes for the accept
“pega.ui.signature.acceptSignature” and clear “pega.ui.signature.clearSignature” actions.
5. Ensure that the signature name and category parameters are defined for each function to
uniquely identify the control on the screen.

391
The Attach Content Control
Add the Attach Content control to a desktop or mobile application to allow users to attach files to an
application. This control is responsive and can be formatted to display as a button, link, or icon.

Using this control at runtime in a desktop application launches the default file browser window.

The control also works on certain mobile browser, such as Safari on iOS and Chrome on Android
devices. In a mobile application the actions are specific to the operating system.

On iOS devices, users can select an image file from the mobile device’s camera roll or take a photo.

On Android devices, users can select where to retrieve an image file from using a tiled list of applications,
which includes the device’s image gallery, Google Drive, Dropbox, and any other related file storage
application installed.

After initiating the attach process, users are prompted to attach a file. It is not possible to proceed until a
file is attached unless the attachment process is cancelled.

Adding the Attach Content Control

In Designer Studio, add any control from the Basic menu to a layout. Change the control to Attach
content.

Once the control is configured to use Attach Content, use the field on the General tab to specify how the
control appears to users. There are three options: Button, Link or Icon.

392
The Content Type is set to image by default . There are three options for the File Name.

 Default – The file name is assigned by the device

 Property Reference – Use this option to set the name of the file from a property reference
 Text – Use this option to provide a hardcoded name for the file
These options are only applicable to mobile devices. The desktop version of the control provides a user
interface that allows for the label and category to be changed, but the original file name is used.

Specify the Category by selecting an existing attachment category or by providing a property reference.

393
Configure an Application for a Mobile Experience
Next we will look at a few settings that affect how the controls are presented on a mobile device.

Date Time Control

The Date Time control can be selected to render using their native control on the mobile device.

The following shows the native date control in iOS.

Text Input Control

The Editable Format on the Presentation tab allows us to define the information going into the field.

394
The mobile device uses this information to show appropriate keys to the user when entering the value.
For example, if the type is set to phone a numeric keyboard is shown.

Link and Icon Controls

The link and icon controls allow us to specify a Type on the Presentation tab.

The type defines which application to open on the mobile device. Use the adjacent field to provide the
details.

395
This is what happens when the link or icon is clicked.

 Email – The email composer opens with the value populated in the To: field
 Phone – The phone dialer or another configured phone application opens
 URL – Opens the URL as a link in a new window
Clicking a link or icon of type phone on iOS looks as follows.

Touch ID
Touch ID is a fingerprint recognition feature built into Apple iOS devices. It is possible to use Touch ID to
login to a Pega mobile app on an Apple device. Select Remember me with Touch ID if you want to be
able to use Touch ID with your application.

This feature is enabled by default. It can be disabled by setting the weblogin/mobile/enabletouchid

dynamic system setting to false.

396
 Module 12: Localizing Pega Applications

This lesson group includes the following lessons:

 Creating a Localized Application

 Translating the Labels and Messages

397
 Creating a Localized Application

Introduction
Localization is the process of adapting the user interface to meet the requirements of local markets and
different languages. A localized UI should reflect correct linguistic, currency, and time and date
conventions that the target market uses. Pega 7 takes advantage of client machine and browser locale
settings and provides features that let you customize the locale settings to suit your localization
requirements.

At the end of this lesson, you should be able to:

 Explain the importance of a localized user interface

 Describe the locale settings in the client machine and browser

 Explain language-specific rulesets

 Override the locale settings for a Designer Studio session
 Customize the locale settings in the operator record

398
Why Localize Your User Interface
Multi-national enterprises realize that localization is critical to achieving higher company revenues and
expect global operations to accelerate. A key success factor is a user interface that communicates
information clearly and accurately regardless of the language requirements and locale standards.
Typically, the application’s interface must maintain a standard company look and feel regardless of the
locale, while at the same time account for the differences that are inherent in a multi-national
marketplace.

For example, below is an example of the U.S. version of a company website:

And here is the website for the German market:

399
We can see similarities such as colors, fonts, and layout which project a standard company brand. The
differences include the languages as well as the date formats (highlighted above).

The expectation is that a Pega 7 application can support users who:

 Work in different languages from each other, or in multiple languages

 Work in different time zones from each other and from the time zones of the server or servers
 Follow local cultural conventions for presenting dates, numbers, and times
Localization of key elements in the user interface can occur while these users share the common set of
underlying rules, logic, and business benefits the application provides.

Localization capabilities increase the value of your application by allowing enterprise-wide or worldwide
use without extensive training, reconfiguration, or replication.

400
Using Client and Browser Locale Settings
The Pega system by default uses the locales that are set in the environment settings of the client
machine. These changes are configured during the installation of the operating system and can be
changed if required. Locale settings are used with language-specific rulesets to control the localized
presentation of our Pega application interface.

Setting the Client Locale

Every Windows workstation has a locale setting, recorded in the Clock, Language, and Region control
panel.

Making changes in the control panel impacts all programs running on the machine. Pega detects this
setting and uses it automatically to determine the formats for dates, times, currencies, and measurements
both on display and input.

Selecting the Change the date, time, or number format link on the control panel lets us select the
German format so that a German user can enter and view dates in the format 06/05/2015 (May 5, 2015)
while a user in the United States uses dates in the format 05/06/2015. Similarly, the German user sees
15:06 as the time when a United States user sees 03:06 P.M. as the time.

401
Advanced settings available from this dialog let us view or customize the default numbering and currency
formats.

The client settings also allow the time zone to be set for the locale. For example, selecting the Set the
date and time link on the control panel lets us set the time zone for the German (Berlin) locale.

The internal representation of dates and times supports both users. This capability requires no Pega
system configuration, and, for most Windows workstations, no additional font installations.

402
Setting the Browser Locale
The browser settings are another place where we can override the locale used for webpages. Updating
the browser affects all websites opened using that browser. For example, in the Internet Explorer
browser, we can choose Internet Options and set language preferences.

In Chrome, the language settings are available in the Language and input settings button in the
Advances Settings group.

403
How Locale Settings and Language-specific Rulesets Work Together
The locale settings control the presentation of text (such as field labels, captions, and titles), dates, times,
and currencies in our Pega localized applications. Text translations are defined in UI-based rules such as
field values, message rules, paragraphs, and sections, which are included in language-specific rulesets.
Other rules such as data transforms and HTML rules are used to localize dates, times, and currencies.

When our locale is the same as a language-specific ruleset to which we have access, we see the
translated text as well as the localized currency symbols, and date formats on our application’s user
interface.

A language-specific ruleset name consists of a base English ruleset name followed by a single
underscore and a locale setting that indicates the language. For example, the Pega-EndUserUI_de
ruleset contains standard UI rules translated into German that are displayed in user forms and portals.

Typically, we use the Localization wizard to create language-specific rulesets.

404
Overriding Locale Settings in Designer Studio
We can override these locale settings for a specific user session in the Designer Studio by selecting User
Interface > Localization Tools > Locale Settings. The Locale Settings dialog provides various options.
Let us take a look at each of them. Here is an example of the dialog when we first open it.

We can click the Settings button to view the current setting. The values are referenced from the browser
language setting and client time zone setting.

Let us use the Demo feature to see how the locale settings affect the presentation.

In the Locale Settings dialog, we change the locale and time zone to Chinese and Asia/Shanghai,
respectively and add the ISO currency abbreviation for Chinese yen. We then click Update to save the
locale for the current session.

405
We click Demo to see the effects of the update. Note that the locale and currency settings are in Chinese
and Chinese yen, respectively.

Note that the text describing day and year are in the Chinese language. The Currency values are in
Chinese yen. We can select other locales in the Locale field and click Compute to see the effects in the
Selected locale area.

406
Note: Compute is run on the local workstation. If you are trying this on your local machine, make sure
that your machine is capable of running a JAVA applet. Otherwise, you will not be able to see this work.

When the user logs out and logs back in, the system reverts to the original default settings.

In cases where we want users to be able to switch locales during their sessions without having to log off,
we can use the engine API named setLocaleName to change locales programmatically. For more
information, consult the Pega API document by selecting the APIs > Engine menu item in the Designer
Studio header.

407
Using Locale Settings on the Operator Record
When managing work in an organization that operates in multiple geographical locations and time zones,
we should be aware of locale-based settings on the operator record. We can use these settings to
override the browser and client machine settings if necessary.

Default Locale Setting

On the record’s Profile tab, the Localization section contains the Default locale field. We can associate an
initial locale with this operator that affects the processing and presentation of dates, times, and numbers.

Enter a locale code for the desired locale. The standard codes in the format aa_BB_CC, where aa
represents the language and _BB or _BB_CC represents a country variant suffix. For example, it_IT is
the locale for Italian as spoken in Italy, de_DE is German as spoken in Germany, and de_CH is Swiss
German.

For example, enter de_DE to use the German display mode for dates (DD.MM.YY) rather than the
American mode ( MM/DD/YY).

If the Internet Options locale setting for a user's workstation applies to the localized application, leave this
field blank. If we enter a value in this field that is the same locale as the language-specific rulesets that a
user can access, the user can work with an entire localized application regardless of the workstation
locale.

408
 Translating Labels and Messages

Introduction
The localization process overrides text in user-visible field value rules that appear in application elements
such as user forms and portal displays. Text includes labels, captions, messages, ToolTips, and
instructions. To present a localized version of the application, we override the rules in our application
ruleset with translated copies in a language-specific ruleset.

The Localization wizard streamlines the localization process by automating many of the steps necessary
to create language-specific rulesets. Pega language packs and auto generated translation spreadsheets
assist you with creating accurate and customizable translations for your specific application.

At the end of this lesson, you should be able to:

 Describe and create localizable field values

 Describe and create localizable message rules
 Localize user interface labels and text using the Localization wizard
 Create a custom language pack using the Localization wizard

409
Creating Field Values for Localization
We use field values to support localization of words, phrases, and sentences that appear on portal
displays, reports, and user forms. Using field values rather than literal text in labels gives us the
advantages of reusability and ease of maintenance.

What are Localized Field Values?

Localized field values (which are copies of the English-based rules) contain text that has been translated
and are associated with language-specific rulesets. Most standard Pega field values are already
translated in Pega language packs. When we use a language pack with the Localization wizard, the
values are included in the standard language-specific rulesets that are imported to the system during the
Localization wizard process.

We can localize field values that we create by doing either of the following:

 Enter the translation directly in the field value and copy the rule into the language-specific ruleset
 Leave the field value untranslated and have it translated in a language package spreadsheet
during the Localization wizard process
Let us look at an example of a localized version of a field value that we plan to copy into a language-
specific ruleset (Spanish) for use in the Spanish locale. We have a checkbox control using a property
called .TermsAndConditions. Currently, the property has a caption that is a text string, which says “I agree
to the Terms and Conditions”.

We want to convert the text into a field value so that we can translate it into Spanish and save it into our
language-specific ruleset.

To create the field value, we open the checkbox properties panel. The Checkbox caption field contains
the text we want to translate.

We enter the name of the new field value in the field and click the magnifying glass to create the rule in
the language-specific ruleset (ending in _es).

410
On the field value Localized label tab, we enter the translated text in the To text area and save the rule.

We return to the checkbox properties panel and submit the update. When the user’s locale is the same as
the language-specific ruleset, the text displays in the browser as shown below.

411
Creating Messages for Localization
We can localize message rules in a fashion similar to field values. The message text is captured by the
Localization wizard making it available for translation.

In our example, there is a validation rule that includes an error message, which is written as a text string:
“The Start Date must be a future date.” We want to replace it with a message rule so that the text will be
translated during the localization process.

Here is how the rule currently looks.

We open the message in edit mode and replace the text string in the Message field with a message rule
name. We then click the magnifying glass.

On the Definition tab, we enter the text that will be translated.

412
The message appears in the validate rule as shown below.

After the message has been translated and added to the language-specific ruleset, the error message
looks like this on the user form.

413
Using the Localization Wizard
Localization is the process of adapting internationalized software for a specific region or language by
adding locale-specific components and translating text. Pega automates the process by supplying a
Localization wizard that we can use to translate the text strings in labels, captions, instructions, and so
on, that appear in the Pega user interface. The process creates a translation package (an Excel
spreadsheet) in which we enter translations or overwrite them if required. When uploaded, the system
creates a language-specific ruleset that contains the translated values.

Using Language Packs with the Wizard

Pega provides language packs for several languages under license. A language pack contains a
collection of language-specific rulesets to support localization of applications. The rulesets contain
standard rules such as field values, messages, and paragraphs that localize the text, currency, date, and
time formats that appear in the standard user forms and portals. Language packs greatly reduce the effort
needed to localize applications. For example, the German language pack consists of rulesets
Pega-ProCom_de and Pega-WB_de containing hundreds of field value rules. Consult Pegasystems
Global Services for more information about available language packs.

Using the Localization Wizard

The wizard can be started in either of two modes:

 Create a translation package

 Upload the completed translated package to a language-specific ruleset

Creating a Translation Package

Select Designer Studio > User Interface > Localization Tools > Translate to New Language. The wizard
consists of four steps.

1. Select Languages — Select the language into which you want to localize the application. The
options list all the possible languages. We are not restricted only to the language packs
shipped in the product. When we complete this step, the system creates a Localization
wizard work object using the prefix pxL.

414
 Select Rulesets — Select the rulesets you want to include in your translation package. The
package includes the text strings used by rules in these rulesets.

We can select Include all PegaRULES application rulesets so that all the standard Pega
field values are included in the translation package. If we have a language pack installed, the
standard values are automatically translated in the language-specific rulesets. We also have
the option of turning off the language pack so that the values can be manually translated.

2. Enable Records — Start the process of enabling and validating the selected records. When
the process completes, we see rules in the Errors list that require manual updates. To fix a
rule, we click the link in the Rule Name column to open it.

415
 3. Export Translations —The system generates the translation package. The system creates
an XML file for all the text strings that require translation. We can download this as a zip file
and then open it in an Excel spreadsheet to see the fields.

The team can now work on updating the translations for all these strings in the spreadsheet.

Uploading the Translation Package to Our Application

When the translation process is complete, the spreadsheet is packaged into a zip file. We are ready to
upload the contents of the package to the application. We select Designer Studio > User Interface >
Localization Tools > Translations in Progress. In the first panel, we select the wizard work item for the
package we created. We then complete three steps.

1. Import Rulesets — We select a new default language-specific ruleset created by the system
to store the translated strings. So that the translations can be shared across applications we
would select an organization ruleset.

We add this ruleset to the access groups that require translations. The system automatically
displays the translated text when the user interface is rendered in the same locale as the
language-specific ruleset.

2. Upload Translation Pack— We import the zip file that contains the translations.
3. View Import Results — The system imports the translations and creates the ruleset and the
associated rules required to save the translated strings.

Select User Interface > Localization Tools > Locale Settings to see the user interface in the localized
version. In the Locale Settings dialog, select the desired locale in the Use Locale field. Here is an
example of a user form that has been translated into German.

416
The label “Ursprung” shown above uses the translated version of the standard field value “Origin” located
in the Pega-ProcessCommander_de language-specific ruleset.

Creating a Custom Language Pack

To create your own language pack that includes standard Pega field values, do the following:

1. Run the Localization wizard using the Translate to New Language option. Use a ruleset that
does not contain any significant user interface rules that reference field values—for
example, an organization ruleset.
2. When you reach Step 2 in the wizard, include all the PegaRULES application rulesets and
select the Action option Include pega translation and export for custom translation.
This creates a translation package that contains all the standard Pega field values.

3. When the file is complete, import it to a top-level (organization) application ruleset so that it
can be shared across business applications. Field values in language-specific rulesets use
normal rule resolution. Your custom language pack cannot be imported to a standard locked
ruleset such as Pega-ProCom (where Pegasystems language packs are located).

417
 Module 13: Accessibility

This lesson group includes the following lessons:

 Designing Accessible Applications

418
 Designing Accessible Applications

Introduction
Pega provides tools and features that allow us to build user interfaces that can be accessed by users who
need assistive technologies. Using these Pega capabilities ensures that all users including those with
disabilities can achieve identical efficiency and productivity in any Pega application.

At the end of this lesson, you should be able to:

 Define the purpose and importance of an accessible application

 Define Web Accessibility Initiative (WAI) and its guidelines that include Web Content
Accessibility Guidelines 2.0 (WCAG 2) and WAI-Accessible Rich Internet Applications (ARIA)
 Describe the many standard Pega features that are accessibility-friendly
 Describe how to set up an accessible UI using the WAI ruleset
 Implement basic accessibility guidelines and best practices

 Use the Accessibility Report to test the accessibility compatibility of the application
 Describe accessibility best practices when designing layouts, controls, and grids

419
What Is an Accessible Application?
An accessible application is one that can be used by people with disabilities of various types, including
people who cannot use a computer mouse and people using assistive devices, such as screen readers,
voice synthesizers, or screen magnification programs.

Initiatives are under way to mandate that disabled users have equal access to Internet resources,
including the guidelines issued by the Web Accessibility Initiative (WAI) of the World Wide Web
Consortium (W3C) and, in the United States, the amendments to Section 508 of the Rehabilitation Act of
1973 or the Americans with Disabilities Act (ADA). The result is that Web interface design is intricately
tied to accessibility design. As user interface designers, it is our responsibility to understand and support
the needs of disabled users.

It is important to consider the needs of individuals with disabilities during the initial application
development phase. Adding accessibility features later in the development process is time-consuming
and expensive.

Accessible Designs Help All Users

Features included to improve a product's accessibility are generally consistent with good design practices
that will benefit all users. For example, full keyboard navigation provides the necessary functionality
required by assistive devices, and allows power users to keep their hands on the keyboard without having
to navigate with a mouse pointer. Let us look at an example where accessibility and good screen design
go hand-in-hand.

Color contrast is one of the most commonly known accessibility issues. To meet the minimum
recommended accessibility, large text (19px bold and above or 24px regular and above) has to meet a
minimum contrast ratio of 3:1. Other visible text within our screen has to meet a minimum contrast ratio
of 4.5:1.

The company’s web page below uses yellow with white, which has a color contrast of only 2:02:1. If
paired with black, the yellow on the screen would meet the highest level of color contrast and ultimately
be easier to read for all users.

On the other hand, this company’s web page uses green with white, which has a color contrast ratio of
5.9:1 and far exceeds the accessibility requirement. As an additional benefit, this web page is easier for
all users to read.

420
The Business Imperative of Accessibility
The ability to design accessible applications becomes particularly important as more users begin to
access computers in nontraditional ways. Federal, state, and local government agencies, educational
institutions, and private companies that must comply with the ADA or with all the guidelines from Section
508 need to consider the accessibility of the products their employees and customers use. Therefore, we
should remember that an accessible product has several marketing advantages over its competitors.

421
Accessibility Guidelines
Our applications should meet at least the minimum standards for web accessibility as defined by the Web
Content Accessibility Guidelines 2.0 (WCAG 2). These guidelines are widely regarded as the international
standard for web accessibility.

WAI-ARIA
Recently, the W3C introduced the Accessible Rich Internet Application suite (referred to as WAI-ARIA) in
response to the development of dynamic content and user interface controls that use rich-client
technologies such as JavaScript, Ajax, and DHTML (Dynamic HTML). WAI-ARIA increases the
accessibility of web pages by adding semantics and other metadata to the HTML content. This semantic
information enables assistive devices to access rich content available on the screen document.

WAI-ARIA provides us with the following:

 Roles to describe the type of widget presented, such as "menu" and "treeitem"
 Roles to describe the structure of the Web page, such as headings, regions, and tables (grids)

 Properties to describe the state widgets are in, such as "checked" for a checkbox, or "haspopup"
for a menu.
 Properties to define live regions of a page that are likely to get updates as policy quote totals or
sections that refresh based on user input.
 Properties for drag-and-drop that describe drag sources and drop targets
 A way to provide keyboard navigation for the Web objects and events, such as those mentioned
above

422
Pega Accessibility Features
Using WAI and WAI-ARIA standards and technology, Pega has designed accessibility features directly
into many standard interface components. These include the following.

 Keyboard accessibility — Tab, Enter, ESC, and arrow keys can be used to navigate in all
navigation components, focusable elements and actionable elements on the screen. These
include screen and accordion layouts, dynamic containers, section tabs, grids, modals, menus,
and others.

 Document level accessibility — On a desktop, the first field in the document gets focus when
launched. The document also has a lang attribute that announces the language. The harness
title defaults to Harness Description + Label of the case so that a screen reader can read the title.
 Error messages — Focus of the page is reset to the topmost error message once a page with an
error displays. Field level errors are also read by the screen reader.
 Skin — The standard skin offers the correct contrast ratio when used with standard portals for
users with reduced vision and color blindness.
 ARIA tags and attributes are added to controls in our application. UI generation automatically
adds the roles and states so that assistive technologies can determine the semantics.

ARIA Configuration
ARIA states and properties allow further information about the widget to be provided to assistive
technology to help the user understand how to interact with a widget. States and properties are aria-
prefixed markup attributes. The standard Pega application adds to the document widget attributes such
as:

 aria-autocomplete

 aria-checked (state)
 aria-disabled (state)
 aria-expanded (state)

 aria-haspopup

PegaWAI Ruleset
Pega includes a special ruleset named PegaWAI in the installation bundle, which contains additional
accessibility features. These include alternate versions of certain controls, additional JavaScript to alter
behavior for accessibility, field values that enhance callout in screen readers, and when rules that act as
switches for these different features.

To enable the PegaWAI ruleset we need to import it into the application. We then add the ruleset to the
Production Ruleset list on our application. Finally, we add the ruleset to the access groups of developers
and users needing accessibility features and controls. On the access group’s Advanced tab, we enter the
ruleset in the Production Rulesets list and click the Enable accessibility add-on checkbox.

423
When users log in they see the screen formatted for enhanced accessibility. Many controls and labels are
formatted differently. For example, the date control displays as a dropdown box instead of as a calendar.

Some images used in field labels such as the required icon are rendered as text descriptions.

424
Accessibility Compliance Guidelines
The following table provides guidelines we follow when designing an application for accessibility.

Checkpoint Things to Do Things to Avoid

Labels Use terse descriptive text that is non-
technical, simple, and clear.
• Using technical terms.
• Repeating a word in
labels. Instead, use a
header to group
information. For instance,
“Rating start date; Rating
end date; Rating.”

Input Fields • Mark required fields. • Disabling inputs. Instead

use visibility expressions
• Use placeholder text to provide a ‘hint’ to and visible When rules.
aid the user with data entry. For example
the expected format; type of data, • Using programming
constraints on input: terminology in
placeholders.
o Date = “dd/mm/yyyy”
• Using labels on
o Number = “numbers only” checkboxes. Instead, use
captions.
o Dropdown = ‘Select…’

o TextArea = “Max of X
characters’” with display counter

• Use a read-only caption to the right of

checkboxes.

Buttons, Links, and • Use a descriptive term that is business Using the following:
Icons friendly or is an established UI
convention. • Terms such as “click
here”. Screen
• Use tooltips that are insightful; for readers focus on the
example, “Delete item from list” for a text within buttons
delete icon. and links so it needs
to describe what the
action will do.

• Pega terminology
such as assignment
or local action.

• Icons without a tooltip.

425
Checkpoint Things to Do Things to Avoid

Event Behaviors • Use single-click events for buttons, links, Using the following:
icons and grid actions.
• Hover events
• When using onChange:
• Hover events (tooltip
o Selects have Pega standard is acceptable as its
accessible alternative in the functionality is
PegaWAI ruleset. controlled by the
browser or user
o Checkboxes and radio buttons: agent)
make sure that visible when
conditions apply to layouts below • Double-click events
the input.

o Use client side visibility as much

as possible instead of refreshing
the section.

• Use keyboard events as well as click

events for grid row actions.

Grids • Use a percentage setting for width. Using the following:

• Use a link or a button in the bottom • Pixels (fixed) width on

action area of grid to ‘Add Item’. the presentation tab

• Use a delete link or icon on the row for • Double-click events

deleting a row/item.
• Pagination format
• For pagination use ‘Page 1,2,3…’ format ‘Page 1 of X’
and place in the bottom action area of the
grid.

• Use the Enter key and Spacebar to

trigger row event.

• Include a grid summary on the general

property panel; use a concise description
of what the grid displays.

Error Prevention • Validate user data entry with client side Relying on technical or
and validation rules. verbose explanations; for
example, “1 of the following 3
• Screen flows are reversible. Users fields is required. Name OR
should be able to go back to make Postcode OR 1st line of
changes. address”.

• Users have the ability to go back or

update information prior to finishing the
process.

• A review screen is available with an

option to go back to process steps.

426
Checkpoint Things to Do Things to Avoid

Error Messages • Set ‘full text error messaging’ on the Using the following:
harness (only before Pega 7.1.5)
• Technical terms; for
• Use Contextual error handling with example, “is not a
Property Set Message. valid double”

• Add a concise description of what is • A Page Set Message

wrong and how to correct it. for input level
handling

Styling – Fonts, colors, • Keep all styling in the skin. Using the following:
and inputs
• Check color contrast (use either of the • Inline styles
following tools).
• Font sizing in PT units
Firefox Color Contrast Plugin
https://addons.mozilla.org/addon/wcag- • Color alone to convey
contrast-checker meaning; for instance,
red or green for status
WCAG color contrast checker
http://contrastchecker.com/

Help Provide context-sensitive help (SmartTip), on Using SmartLabel or

click – keep it concise. SmartInfo.

Keyboard Accessibility • Make sure that the keyboard provides all Excessive scrolling or mouse
page functionality in a logical order. movement in order to use
action buttons or links.
• User should be able to use the Tab key
on the keyboard and navigate in a logical
and consistent manner.

427
Accessibility Report
Pega includes a report to test the accessibility compatibility of the application by going to Designer Studio
> Application > Tools > Accessibility Report. We can run the report only after adding the PegaWAI ruleset
to our access group. The report groups all rules as harness and the sections referenced by flow actions.
Drilling down further we can see all other referenced rules and controls. The report indicates compatibility
percentage for each element. Note the TabbedScreenFlow7 harness, which has a score of 0%.

When we drill down and hover the mouse pointer over 0% next to the element, we see that it is a non-
auto-generated rule. It appears because the accessibility flag is not enabled.

By default, accessibility is enabled for all auto generated rules. In this example, we can click the element
on the list to open the rule and reset the Accessibility checkbox to Yes.

In general, we should test other rules and enable this flag.

We can hover the mouse pointer over other elements to see why they are not accessible. In some cases,
a priority appears indicating the nature of the accessibility violation and an alternative of how to address
the violation.

428
Example 1: Designing Accessible Layouts and Controls
We have discussed why designing for accessibility is important and provided some design guidelines.
Now let us put what we have learned into action. Do not forget to follow usability best practices as a well-
designed screen is especially important to users who use accessibility devices.

Below is an example of a form for collecting information when a customer applies for a new phone
contract that does not represent a good accessibility design.

At a glance, the form seems easy to read. However, a user that has an accessibility device will likely
encounters issues. Here is how the section looks after we have designed it for accessibility.

How are they different? Below are some of the modifications we made.

429
Note: Our revised screen relies on good design practices and accessibility capabilities built into the core
product. We would use the PegaWAI ruleset only if we needed additional enhancements, which in many
cases, are not necessary.

 To ensure that keyboard navigation follows the intended visual order on the screen we group
customer information in two logical vertical columns. Each column is an embedded dynamic
layouts inside an inline grid double dynamic layout. The Tab key navigates within the column and
then to the next column when the last field in the first column is reached.

As originally configured, the fields were in the same dynamic layout. Tabbing out of the Customer
First and Last Name field navigates to the Monthly fee field rather than the next logical field,
Customer Age.

 Use placeholder text to provide hints on expected content or format. Also avoid repetitive labels
and use a header to summarize the information in the group. Below are the original fields.

430
 We updated the form to look like this:

 Use controls that work well with assistive technologies and follow usability best practices. Below
are two examples.
o We replaced the Frequent Caller, Gender, and Call Reason controls with radio buttons.
For users with motor disorders or who use alternate pointing devices, radio buttons make
it faster and easier to accurately select the right option.
o We changed the Age field from a Text type to a Number type. Where appropriate, we use
Number or Integer property types (which set HTML5 properties that assistive
technologies can use to inform the user that it is a numeric input field).
 Avoid tooltips that are purely decorative. Also, do not use terms such as “click here” for linking.
The term will be read by a screen reader and give the user no context. Here is the original.

We have updated the link that explains what the action does. The tooltip that provides the
necessary context for non-sighted users.

431
Example 2: Designing Accessible Grids
When we design grids, accessibility needs to be addressed. Here are some key points to be aware of.

 Do not use fixed pixel width display. Instead, use a percentage.

 Do not use Page 1 of X pagination. Instead, use the sequential format.

 Do not leave out Grid Summary as it provides functional information for screen readers.

 Make sure column headers are associated with the data, especially for editable inputs.

432
 Avoid the use of the double click action on an item for the following reasons:
o It is not a common convention in Web applications.
o It is difficult to inform users of alternate pointing devices that double action is required.
 Only use click to set focus if the item requires an action. For example selecting an address from a
list before submitting is valid.

433
 

Module 14: Extending UI

This lesson group includes the following lessons: 

 Extending the Capability of the Skin

 Building Dashboard Widgets
 Creating Purpose Specific Controls

 
434
 Extending the Capability of the Skin

Introduction
In some instances, we might need to customize our Cascading Style Sheets (CSS) to modify the
presentation of on our screen that are not easily configurable in the skin. There may also be
requirements for unique styles that we want to apply only to a custom control or layout.

Similar to the CSS files we import when adding style sheets, we can import web fonts to supplement the
standard fonts supplied by Pega.

This lesson describes how we add or create these styles in a skin and apply them to our user interface.
We also demonstrate how to import web fonts into your application.

At the end of this lesson, you should be able to:

 Add style sheets to a skin and apply them to UI components.

 Create custom styles in a skin and apply them to UI components.

 Add and apply styles sheets in a harness.
 Describe the sequence in which Pega applies styles
 Describe how to add webfonts to an application.

435
Using Custom Style Sheets
When we render a screen, its appearance is controlled by the style settings in our skin rule. As we
learned in a previous lesson, the skin rule specifies the presentation of the content layer, including
typography, borders, backgrounds, layouts, and UI placement and alignment. In addition to the auto-
generated CSS styles set in the skin, we can add our own CSS style sheet files to present a look and feel
that meets our custom requirements and may be difficult to configure using component styles and mixins.
Like the skin’s CSS styles, the included style sheets are applied to the entire content layer.

Adding Style Sheets

We begin the process by opening the Included styles tab on our screen’s skin rule.

1. Before we add our style sheet, we should make sure that we generate styles only for the
components we need. On the tab’s CSS support section, select Standard Pega application
(components we’re likely to use), or Custom (to select the components individually) In the
Support presets dropdown.

2. Now we are ready to add our style sheet. Click the Add style sheet link in the Additional
style sheets section to display the first row. In our example, we are adding a style that
changes the appearance of disabled buttons. We enter the style sheet’s name in the row.

436
 Note: The order in which you enter style sheets is important because the bottom style sheet is
applied last. To re-order style sheets, select the number beside the file name and drag and drop it
to the correct location.

3. We then click the plus icon to create a new CSS text file. In the new record form, we keep the
default directory and CSS file type.

4. On the text file form’s Main tab, we click the Upload File button to open the Upload File
modal dialog box. Then, we select the CSS file we have created for disabled buttons.

When we click the Upload File button, the CSS source appears in the File source text area on the
tab.

437
 5. We save the text file and the skin rule.

We can test the results by opening a button on our screen using the Live UI tool.

On its properties panel we set Disable to Always.

When we refresh the screen, the button appears as shown here.

438
Using Custom Styles
The skin rule provides a broad array of styles that provide almost unlimited flexibility when designing our
screen’s presentation. In special situations, we might want to create custom styles that can be applied to
individual cells or to layouts and can be reused.

Creating Custom Styles

To create a custom style in the skin rule, select the Custom styles component on the Component styles
tab. Click Add Item to add a row.

In the Style Name column, enter a description of the style’s purpose using lowercase characters and
hyphens, as needed. Note the primary category of purpose first, for example, "textalignCenter." By
default, custom_ is prepended to the class name that you specify.

In the CSS column use the Style Editor to create the CSS code in the CSS column. Click the magnifying
glass at the end of the row to open the Style Editor. Use the down arrows to select the styles you need.
The selected styles appear in the right column.

When we apply our edits, the style appears on in the custom styles row as shown below.

439
Applying Custom Styles
We can apply custom styles to layouts and cells. For example, we can add a custom style in the Inline
CSS class field on the screen layout properties panel.

We can also use custom styles in the Dynamic layouts properties.

We can apply custom styles in the Advanced Presentation Options section on Cell Properties panels. We
can apply them to one or both of the fields.

440
About Inline Styles
Inline styles can be applied in many properties panels using the Style Editor.

We should not use these styles for the following reasons:

 The styles are not reusable and must be applied individually.

 The styles are difficult to maintain. If you want to modify or remove an inline style used in multiple
components you must find and update each one. In contrast, style sheets and custom styles can
be centrally maintained in the skin rule.
Previously, inline styles were used mainly for testing purposes. Capabilities provided by the skin rule,
custom style sheets, and custom styles eliminate the need for inline styles.

441
Applying Custom Style Sheets to Harnesses
Including style sheets in the skin rule ensures that the styles apply uniformly to all harnesses throughout
our application. However, we might want to use custom style sheets for specific harnesses such as
harnesses embedded in sections.

For example, a dashboard harness is embedded within the Case Manager portal harness shown below.

Additional style sheets, which apply only to the dashboard harness, have been added.

Below is a segment of the pxDashboardStyles CSS file that describes a style that applies only to the
dashboard.

    

442
How Pega Applies Styles
When Pega renders the screen, the styles are applied in this order.

1. Inline styles — Styles entered in inline style fields on the Properties Panels.
2. Harness style sheets — CSS style sheets listed on the harness rule’s Scripts & Styles tab.
3. Skin rule’s auto-generated CSS. The skin used depends upon the portal and application rule
settings.
a. Portal – If we have specified a skin other than the application skin on the Details tab,
Pega uses the selected skin.

b. Application — If the default application skin is set in the portal, Pega uses the skin
defined in the Presentation field on the application rule’s Definition tab.

Within the skin, the included CSS style sheet files and the custom styles are processed first.
Finally, the styles and mixin settings in skin are processed.

Conclusion
We can create styling components using mixins and other formats in the skin rule. However, Pega also
gives us the ability to add CSS style sheets in a skin rule or applied to a harness. We can also use
custom styles defined in a skin. In addition, we learned about line inline styles defined directly in layouts
and cells.

443
 Building Dashboard Widgets

Introduction
The Dashboard provides information useful for business users in terms of business metrics and the visual
display of such metrics to make business processing understandable. We learned that a wide variety of
templates and widgets are shipped in the product allowing end users to personalize their dashboards
quickly. Users also have the ability to configure widgets at runtime which allows us to customize the
content we can embed..

Despite all of the templates and widgets that ship with Pega 7, we may need to create custom templates
or widgets to support personalizing dashboards if none of the standard widgets enable us to include the
content we want.

At the end of this lesson, you should be able to:

 Create a dashboard widget

 Create a dashboard template

444
Creating Widgets
We do not usually have to create widgets, but if we want to include a specific section that is application
specific we will need to create a widget. However, before we create a widget we should make sure none
of the existing widgets can handle our requirements.

Let us say we want to create a new widget that is to be added to the portal for our end users. Let us look
at the steps a developer should follow.

1. The widgets present information to users, so we need to create a section because it is the rule
type that can present content to users. We should create a new section rule in a class that is
accessible by the portal and add layouts to them (we can add any layout type that can be used in
a section). We can accomplish this using one of three approaches, but in most cases we will use
one of the first two approaches.
a. Save the section in the same class used by the harness of the portal. The portal rule by
itself, does not apply to any class. This approach is highly recommended.
b. Most of the standard widgets shipped in the product are saved in @baseclass, so we can
save the custom widget there, which makes it available for use by other harnesses.
c. If the end user portals employ its own hierarchical structure, then we could use one of the
classes in the hierarchy so all portals can inherit from there.
d. section.png

445
2. After the section is created, we can add layouts and fields to complete the widget. Then we need
to configure the section as a widget, to do this we need to:
a. Click the settings tab and set the Section type as Dashboard widget.

b. Complete the rest of the fields under the section type such as the widget title and widget
description.

c. The category can be selected from one of the following default categories such as
Reporting, Information, Social, Manage change or Case Management. If none of the
available categories makes sense then we can enter a new category name in the field.
The widget picker automatically creates a new category.

446
d. To select an icon we need to click the icon next to the field which gives us access to the
image catalog. The Image catalog gives us access to all image files that are uploaded as
binary file rules.

447
Widget Configuration Options
We can also configure widgets to accept parameters from users to make the widget powerful. One
example we saw in the Building Personalizable Portals lesson is the reporting widget where users can
choose the report they want to embed in the dashboard.

The highlighted part in the picture offers the ability for users to enter those configurations required to
present the content. Let us go back to the report widget and see how we can set this configuration.

448
Unlike the section rule, we can choose a different name class name for the flow action rule. The flow
action rule as we know in turn references the content that is presented for the user at runtime.

The section is saved in the same class as that of flow action and it is configured to present the content.

449
Creating Templates
Similar to widgets, we can create personalized dashboard templates. Templates again are created by
creating sections.

1. We can create a new section and similar to widgets we need to save it as part of the class similar
to the approaches we discussed in the widget creation. The configuration looks similar to the
widget settings that we discussed a little earlier. We can add the template title and template icon.

2. The section can use a combination of dynamic or column layouts to create the template. Once all
layouts are added, we need to reference or include a section named pxUserDashboardSlot into
the dynamic layout to add widgets in it. Some examples of templates are:

Template1

Template2

450
 3. In both of these templates we need to include the section in each of those cells. After including
the section, we need to enter .pxUserDashboard.pySlots(x) for the Clipboard page field,
where x represents the slot number. So in the template 2 example, we have two slots and in
template 1 example we have four slots.

When creating a new template we need to add dynamic or column layouts and then reference the section
named pxUserDashboardSlot into each cell of the section and then reference the slot numbers
appropriately.

Unlike wizards, templates also allow customization of the shipped templates and it allows adding
additional slots or removing slots or even changing the template type itself. We should remember that
changing the standard template impacts all portals using that template.

Pega ships with a wide variety of templates that serve most of the needs but it also provides
customization options for designers to meet their application requirements. Personalizing dashboards
becomes more powerful with the creation of application specific widgets and templates.

451
 Creating Purpose Specific Controls

Introduction
Controls though mainly used in formatting the presentation of data elements on user screens controls
also determine the behavior of the data element. The system assigns a default control when a new
property is defined and this control can be changed as needed.

For instance, date of birth could be presented in a read-only format when viewing a user profile screen,
but a calendar control can be presented when a user is editing the same profile screen. We know that the
usage of varied controls helps in determining the display.

In this lesson, we will learn how parameters that are available in the standard controls be reused to
display the same control differently. We will also learn about using the skin rule to modify the presentation
of the control. In some cases, we will need to create custom controls and we will learn two different ways
of extending auto generated controls.

At the end of this lesson, you should be able to:

 Configure the parameters to customize the presentation

 Configure skin rule to customize the presentation of controls

 Define your own controls to extend behavior
 Extend the user interface capability by using specialty components

452
Extending Use of Action Controls Using Parameters
Pega 7 comes with several auto-generated controls that can be used as-is without any modifications.
Most of these controls come with parameters that help in using them in varied scenarios.

There are broadly three different control modes as shown here in the control rule definition.

1. Editable/Read-Only – use to present values in both editable and read-only modes.

2. Read-Only – use to present values in read-only mode

3. Action – use when the user has to click for an action to occur
Action Mode:

Let’s start by looking at action mode before discussing the other two modes. Buttons, Icons and Links are
the most commonly used controls in this list.

Let’s take a look at the Options field for the Button, which is the most commonly used control. The button
has a label that appears as a tooltip when you hover over the button. We can also disable the button on a
condition or use a privilege to show the button based on user role.

Buttons also offer styling options – the format can use one of the various formats defined in the skin rule.
By default, three style formats are supported for buttons and additional formats can be defined in the skin
rule.

453
The skin rule lists these formats and there is another Format named Light defined in this skin rule.

The image source field in the button control can reference a binary file rule (if simple image is selected), a
property which has the image path (property) and the Icon if using Icon Class.

The options vary by the action control that is selected. So for example, a Signature shows only a tooltip
and can be configured to disable the control based on a condition or can conditionally be shown or hidden
based on a privilege.

454
Extending Use of Input Controls Using Parameters
Let’s now talk about Read-Only modes. There are two types of controls available in Read-Only mode;
Text and Hidden. If Text is selected, it presents other formatting choices including the option to choose a
style format defined in the skin rule.

There are other choices in the Type field to present other input fields in Read-Only mode.

The type determines the format options that can be configured, for instance in the case of Date, the
system provides the options to determine the format in which the value is presented. This is extremely
powerful because we can use a single control to display dates in different formats by configuring the
format in the field where the control is being used.

If we are using a True/False property, we can customize the label of true and false as shown here.

455
Or we can even use an image to indicate true or false.

Text Input
This is the most commonly used control in user screens to enable users to enter values in a text box. It
offers various choices including selecting a style from the skin rule, specifying the size in parameters, as
well as the minimum and maximum values that a user can enter.

The format area helps in customizing how the value is presented in the screen. The choices in the left are
editable and the choices in the right are in read-only mode. For illustration purposes, we have selected
Number which display additional configuration options specific to numbers such as decimal places,
rounding and so on.

Date
Date is another commonly used input control. It presents two different ways users can pick dates- either
from a calendar or from a dropdown list for the year, month and date.

Date Using TextInput + Calendar

Date Using Dropdown Lists

456
Extending Use of List Controls Using Parameters
There is a sub category in Editable controls which display a list of values for selection. These may take
the form of a Radio button, Select box or AutoComplete. List based controls requires the selection of the
source of the list and this is handled by a parameter defined in the control.

Radio button choices can appear either vertically or horizontally just by configuring the Orientation
parameter.

Again the choices vary with the control type and in the case of dropdown we see additional choices such
as what to display as the option, placeholder text and when to load the choices so that the screen can
render more quickly. However, all controls provide similar formatting options wherein we can use the skin
rule to format the presentation. All Auto generated controls come with standard formats and allows us to
define custom styling formats as well.

457
Defining a New Control
There are quite a few auto generated controls that comes with the product that can be used as-is and
customized by using the parameters and the skin rule. In some cases we might find that we are making
the same set of changes to the parameters. How do we address those changes? We use custom auto-
generated controls. However, we need to make sure we are creating a new auto-generated control only
when it really makes sense. We do not need to create custom controls for a style change because we
define the style in skin rule and reference that format in the control.

Similarly we do not need to create custom controls if the change is not drastic. One example where we
could create custom controls is if similar set of actions are carried out, say if we want a custom submit
button which does a post value and refresh section.

Earlier we learned the definition of the Text Input control. The Pega product development team has
created additional controls which merely extend the Text Input.

So the Text Input control is saved as the Number control which has the type selected by setting the type
as Number.

Similarly the Currency control is defined as a new control just by selecting the Currency in the Symbol
field, which then displays additional configurable fields for configuring the currency.

458
We can define a new auto-generated control by first selecting the control mode and then the UI element.
After selecting the UI element the options and formats change based on the UI element that we have
chosen.

459
Defining a New Custom Control
Pega supports using PublicAPI to create custom autogenerated controls to extend the capability of the
product. This must be used as a last resort only on cases when we are inserting a specific code which is
not supported in the product.

Public API can be accessed by clicking Engine API from the Resources menu.

It launches the entire API library and navigate to find Public API under All Classes.

460
To access a specific method we use the keyword tools.

461
Specialty Components

Specialty components provide capabilities for the developers to build and integrate the third party
components such as jQuery, Flex, Flash, JavaScript in the UI rules of a Pega application.

Specialty components can receive and send data back to the data elements used in our Pega
Application. Pega publishes the API's which can be used to set and get values. Specialty
components support JSON (Javascript Object Notation) type data exchange.

Specialty components support both single level and embedded properties. If a page list is used as a
parameter then all the associated properties are also available in the specialty component.

The specialty component is saved in a section rule which makes it reusable, and also supports rule
specialization and rule resolution and behave similarly to any other section rule.

The specialty component is recommended since it offers the ability to leverage other UI rule
capabilities. The section rule that is marked as a specialty component can be included in other auto-
generated rules. Specialty components minimize the need to build custom UI on top of our
application to support features that are not possible to build using the designer canvas.

Review this PDN article https://pdn.pega.com/pegarules-process-commander/about-specialty-

components for more information about specialty components. The article and the linked RAP are 62
specific and there are some changes in 71 for to include charts such as gauge, funnels easily using chart
control. In short, Specialty Components are mostly useful for embedding jQuery in the UI.

462
 Module 15: UX Methodology

This lesson group includes the following lessons:

 DCO and UX
 Methodology and UX

463
 DCO and UX

Introduction
On many projects, the user experience (UX) strategy is an after-thought. Designing a user interface (UI) is
just one piece of the application development puzzle, and developers often don’t pay enough attention to
UI design. UX concerns are addressed late in the development cycle, if at all.

But UX strategy is as critical and important to the success of a project as the right development
methodology, well-developed requirements and specifications, and good project management.

To achieve the goal of delivering a world-class user experience, you must approach your UX strategy as
a high-level design objective, and develop that strategy as early as possible.

Just as Direct Capture of Objectives (DCO) is an approach to developing software, a UX strategy is an

approach to developing a robust user interface. UI research, design, and validation are part of a
continuous process, rather than discrete tasks to perform in isolation. And just like DCO, the earlier you
include your UX strategy into your overall development plan, the more effective that strategy will be.

At the end of this lesson, you should be able to:

 Align UX tasks to DCO best practices

464
Align UX Activities to DCO Activities
The premise of DCO is simple: incorporate the application design into the application itself as much as
possible, including the objectives, requirements, and specifications. This ensures that everyone involved
with application development understands the design, and can link the design to the finished product.

DCO isn’t a thing, or a specific part of any development methodology. Rather, DCO is a set of tools and
best practices designed to maximize the productivity of application developers. DCO is a process
designed to link an application back to its requirements and specifications, to ensure that the finished
product satisfies its objectives. The return provided by DCO increases the more you apply DCO to an
application and its elements. The earlier you incorporate these elements, the more effective DCO
becomes.

The same holds true for your UX strategy. A good UX strategy doesn’t start with developers creating
sections and flow actions. A good UX strategy starts with discussions about UI needs. These discussions
help to generate UI mock-ups with whiteboards, sketching tools such as Balsamiq, or even pencil
drawings on napkins. And these mock-ups allow you to ask for user input early on, which you can use to
refine your UI designs.

DCO divides application development into four basic steps that can be incorporated into any development
methodology:

1. Gather requirements and create high-level specifications to satisfy them.

2. Elaborate on the high-level specifications to create a design that meets the business’ needs.
3. Construct the application using the elaborated specifications.
4. Test the completed design.

DCO can easily incorporate your UX strategy, because it was designed to do so.

The key to DCO is the DCO session, which brings together the development team and subject-matter
experts (SMEs) from the business to discuss and refine the requirements and specifications for an
application. The goal of a DCO session is to build a consensus about an implementation through an
iterative process of design and review, and reduce errors due to incomplete or unclear objectives,
requirements, and specifications. The iterative nature of the DCO session is well-suited to discussing UI
needs, prototyping the UI, and refining the design based upon user feedback.

465
Once you finish elaborating the UI design, you can advance to the construction step and complete the UI.

466
UI Prototyping for Pega Applications
One key to an effective UX strategy is to prototype each user interface before you construct it.

For each UI prototype, you want to start with a high-level concept and iterate the design to refine and
validate your approach with business Subject Matter Experts (SMEs). A prototype is a valuable tool for
validating your design with SMEs and users. UI prototypes allow UI designers to obtain, analyze, and act
upon high-quality feedback more effectively than by reviewing design documents.

Once you validate the design with the SMEs, you can prototype the design and solicit user feedback
through usability testing. Again, the focus is on iteratively learning from user behavior to design a better
UI.

With a Pega application, you have two options for UI prototyping: in the application itself, or outside of the
application.

The goal of your UX strategy is to prototype as much of the UI within your application as you can. When
you prototype your UI within a Pega application, each design iteration further evolves your prototype into
the final UI. This significantly shortens the time needed to implement your UI, since the system leverages
your prototypes rather than forcing you to recreate them.

You can prototype within your Pega application once your application meets two conditions:

 The class structure already exists, and

 The data model already exists.
Until your application satisfies both of these conditions, you should prototype your UI outside of your
Pega application. Use whiteboards, pen and paper, or sketching software such as Balsamiq or
Sketchbook to design your UI.

During this pre-product prototyping phase, focus on “big-picture” ideas. Keep your designs fluid, and don’t
be afraid to experiment and continuously refine your approach. Your designs aren’t permanent until you
begin prototyping in PRPC, so don’t be afraid to throw your early designs away and start over until you
get the design right.

So when should you start prototyping within your Pega application?

1. The design concept should be stable. If you’re still deciding what information should appear
on a specific user interface, the design is not ready for migration into your application as a
prototype.
2. The process itself has achieved a consensus. Creating the UI for a particular step is much
easier once you know when in the process that the step occurs.
3. Users need to be able to visualize the UI to understand the overall user experience.
Drawings and design documents help to a point, but there is no substitute for actual user
experience. Allowing users to interact with your UI provides higher-quality user feedback
that can significantly improve your UI design.

467
UX Strategy Best Practices
When designing your application UI, keep the following best practices in mind.

Collaborate Early and Often to Solidify Your Ideas

A good UI design is rarely the result of one person’s design. Encourage collaborative development by
through the use of sketches and whiteboard designs. Allow all of the UI designers to contribute ideas to
the design, and let the UI design evolve from these contributions.

And remember that while your goal is to prototype your UI in Pega, you may have to wait before the
application is ready for UI prototyping. Take advantage of this time to experiment with your approach, and
build consensus for the final design. Once your application is ready for UI prototyping, you can prototype
only one design that everyone likes, rather than prototype several designs and have users vote for their
favorite.

Couple the Business Goals to User Needs

Don’t forget that the purpose of an application is to allow end users to perform their work in the most
efficient manner possible. When designing your application UI, focus on what the end user needs to do.
Remember to utilize DCO sessions to validate your UI design against user needs. And prototype your UI
in Pega as soon as possible, so that users can interact with the UI and provide high-quality feedback.

Work Fast
With UI design, small changes can have a large effect. Most prototyping changes can be made quickly,
which allows users to validate your design changes. Remember that you only need to provide users with
an understanding of how a UI should work, and not a fully functional UI. For example, when creating a UI
mock-up, use sample data rather than expend effort connecting to a data store.

When Possible, Develop Your UI in an Agile Manner

You want to be as lean as possible with your UX strategy. However, this does not mean cutting corners
and skipping steps in the design process. Remember to focus on the important aspects of UI design, and
develop in short, iterative cycles to assess what works best for the business and the user. The next
lesson discusses how to adopt a Lean approach to UI development.

Always Validate the UI with Business SMEs

Finally, remember that the business Subject Matter Expert (SME) has the final vote on your UI design.
You might think your UI design is amazing, but if the business users do not agree, no one will want to use
your application.

468
 Methodology and UX

UX and Agile Methodologies

To effectively leverage an agile approach, we need to adopt an agile development methodology. The
customer focus and rapid cycles of agile methodologies act as a form of governance for application
development.

This lesson discusses adopting an agile approach for the Scrum development methodology. The advice
and tips in this lesson can aid teams versed in Scrum as they transition to an agile approach. In addition,
the advice and tips can work with any agile methodology, though you must map the concepts in this
lesson to methodologies other than Scrum.

At the end of this lesson, you should be able to:

 Describe the ideals of an agile approach to UI development

 Place UX activities into the context of a specific methodology

469
Agile UI Design
Adopting an agile approach to UI design is no longer a luxury. In today’s web-focused business
environment, a rapid cycle of experimentation, validation, and refinement is essential to project success.

Successful UI development now requires short, iterative design cycles to assess what works best for both
the business and the user. This approach works well with agile methodologies, such as Scrum, which
depend on short, iterative cycles to keep pace with the changing needs of users.

So, what does an agile approach entail?

 Frame a vision of the problem to solve, and focus on the right outcomes. Build a team that
focuses on user problems and solutions, rather than features to implement.
 Share insights with the team much earlier in the process. Externalize work as much as possible,
either with design sketches or with functional prototypes, to build a virtuous cycle of
experimentation and innovation. Let team members build on each other’s ideas to improve the
final outcome.

 Create prototypes to validate the design and identify ideas that merit further consideration. Avoid
drowning in deliverables, such as design documents. Design documents do notsolve customer
problems. A well-designed product solves customer problems.
 Incorporate the voice of the customer throughout the project cycle, especially when prototyping UI
designs. Answers to the most difficult design problems come from end users. The best way to get
end user feedback is to build something and let users respond with what they like about the
design – and what they dislike.
 Adopt an agile methodology, and concentrate on designing small pieces quickly. Designing and
building a UI in short, iterative cycles, requires a methodology to match.
Remember, an agile approach isn’t about minimizing effort by starting late and limiting the design team’s
activities. Rather, an agile approach is about eliminating wasteful or unproductive efforts to improve the
overall process by letting teams work as efficiently as possible.

470
Agile UX and Scrum
Scrum, as advocated by the Scrum Alliance, is an agile methodology designed to facilitate development
in short bursts, known as sprints. Due to its short development cycles, Scrum is well suited to align
developers with customer needs.

With Scrum, tasks to be performed are cataloged in a product backlog. For each sprint, the development
team moves tasks, known as user stories, to a sprint backlog and assesses the relative difficultly of
completing the task during the sprint. A sprint may last up to 30 days, though two weeks is a more
common duration. Each sprint consists of a series of 24-hour periods. Within each 24-hour period, the
development team conducts a review meeting, called a “stand up”. In this meeting, the team reviews the
work done the previous day, determines the work to be done during the current day, and discusses any
issues that impede completion of their work. At the end of each sprint, the team produces a working
increment of the application.

The overall project consists of an arbitrary number of sprints, numbered from 0 to N. Sprint 0 consists of
planning and other setup work that must be completed before development can begin. Development
tasks occur in the remaining sprints, numbered from 1 to N. Once all of the sprints have been completed,
the application undergoes user acceptance testing (UAT) and performance testing. Once this testing
concludes, the application is released to users.

To successfully apply an agile approach to a Scrum project, we must determine the overall UX strategy
and perform any necessary education in Sprint 0. This allows UI developers to focus on UI design in the
development sprints that follow.

Starting with Sprint 1, each sprint cycle consists of three events, with the goal of releasing a working
product at the end of that sprint:

1. Elaborate the requirements and specs selected for the sprint.

471
 2. Build the UI and other rules.
3. Test the design.
Within the elaboration portion of these development sprints, (Direct Capture of Objectives) DCO sessions
can be used to design a draft UI, develop and refine prototypes, perform usability testing, and document
the design and make any skin changes.

And finally, once we complete development and the application moves into the acceptance phase,
perform research for the next release cycle – including a review of the UI we just built.

472
Avoiding Pitfalls with Agile Methodologies
An agile approach works best when teams focus on the result, rather than any intermediate deliverables
such as design documents. To maximize the effectiveness of the UI design process, build prototypes as
early as possible and allow users to review them as often as possible. This feedback-driven approach to
design allows the team to focus on the end user throughout the UI design process.

Unfortunately, the application of an agile methodology may encourage behavior that jeopardizes this
iterative, feedback-driven process.

Requirements and Specifications Seem to be Drafted on an Ad-hoc Basis

Under agile methodologies, development teams have a high degree of autonomy. Unfortunately, this
increased autonomy allows development teams to introduce new requirements and specifications
throughout the development cycle. To maximize the success of an agile approach, establish clear
guidelines for incorporating new requirements and specifications into the development cycle.

DCO May Not be Fully Integrated into the Methodology

While DCO can work with any methodology, teams need to adjust to the use of DCO. Ensure that teams
understand DCO before they begin development, by educating team members on the concepts of DCO
and the use of DCO sessions.

Development Follows a “One and Done” Model, with Lttle or No Iteration

Agile methodologies depend on the use of short development cycles to quickly develop applications.

Under a “one and done” model, a team performs all of its work in one sprint, releases the result, and
never returns to the design. This “one and done” approach eliminates the opportunity for the team to
iteratively review and refine their designs.

To maximize the value of agile development, incorporate iterative design and review cycles into the
development process. Build prototypes early to obtain high-value user feedback, which the team can then
use to improve the design.

Results of Usability Tests are Not Incorporated into Development Sprints

One of the keys to successfully adopting an agile approach is user feedback. Rather than generating
mountains of design documents, agile development focuses on generating a working design as quickly as
possible for users to evaluate. To maximize the value of this approach, the results of these evaluations
must be incorporated into the development cycle, so that designers can evaluate the feedback to identify
adjustments and iterate the design accordingly.

473