Common UI issues on upgrade of Pega Applications Built on UI-Kit
Every once in a while, things need to be upgraded. Your credit card, your car, your device's software/applications (the list goes on..). Things get outdated, stale, and irrelevant; it's just the way of our constantly changing world.
Nowadays, upgrading applications are a must. The need for upgrade is essential for the following points:
Application needs to be fast and scalable
To be compatible with new systems & tools
No dependency on hardware
To have good support in mobility & accessibility
To be more secure
Improved focus on user experience
UI issues after upgrade
After upgrading pega applications to newer versions, the most common UI issues are misalignment of the layouts, controls and text overlapping over content, browser compatibility issues, etc.
Misalignments or UI distortions may arise due to many factors in a pega application:
Rules being overridden in the application layer
Rules being updated in base layer
Changes to formats in skin
Wrong css selectors being picked from override files
How to identify UI issues after upgradation?
There are ways to identify whether the issues are application specific or due to changes in platform.
Check if the rules has been overridden in the application - If yes, then refer to the ruleset in base layer for how its constructed
Check if the application is using app skin or directly inheriting from UI Kit ruleset
Check whether there is a change in the format present in the skin
Check if any css selectors are wrongly picked from any overridden files
Most common UI issues observed
Issue 1 - Application portal header misalignment:
The application portal header misalignment occur if the header rule has been overridden in the application layer and when the rule is not used directly from UI kit ruleset.
pyPortalHeader section has been overridden, and the application name uses label control and application name label format has a line height of 40px. From 8.1, the application name format label has been updated to not use line height. Refer to the section used in Uikit Ruleset
Update the pyPortalHeader section to use inline middle dynamic layout format, since Portal Header Primary format has been deprecated to align the items vertically centered
Issue 2 - Work area header misalignments
After upgrading the applications, the work area header gets misaligned with wrong padding and different background color. Issue is because of wrong settings in standard container format.
Steps to fix the issue:
Navigate to the application skin
Click on “Containers”
Check “Show legacy styles”
Click “standard format” and update the following settings
Issue 3 - Label elements showing for controls after upgrade
Before proceeding with fix ensure the control is inside a dynamic layout and format for layout is set as “Mimic a sentence”
From 8.1 “Mimic a sentence” format of pyEnduser skin displays labels. Reason behind this intentional change is as labels can be added or removed per control, there is no value in having any OOTB layout format define the label display for any control dropped inside it.
Steps to fix the issue
As a local-change, make rule changes to not show labels for controls (Recommended)
Uncheck “Use property default “ checkbox
Clear text in “Label value” field if any
Override the “Mimic a sentence” format in skin
Use this solution only when then there are too many rules to be updated
Latest changes to this format will not be available as format is overridden
Go to dynamic layouts components
Override “mimic a sentence” format
Change label position value to “none”
Upgrading applications and fixing issues is a tedious work as it consumes lots of time and resources. It is always advisable to follow the best practices to avoid the number of issues
Best practices to be followed to avoid ui kit upgrade issues
Don’t name the rules in the application the same as in UI kit ruleset
If any rule is overridden, check the same rule in the UI kit layer for how its constructed.
CSS files should not be overridden in the application layer with the same name as in Uikit rule
Custom css files should be included for any custom styles specific to application
UI-kit is a showcase of the Pega Design System and is updated every release to stay in sync with the changes in the design system. As such Pega does not guarantee backward compatibility when upgrading from one ui-kit version to the other: after upgrading to ui-kit some of the colors, icons, styling or default behavior of your application might change. Upgrading to a new UI-Kit version is a development effort. While we try to make it easy to upgrade to the latest version of ui-kit, some of the override CSS and sections from ui-kit that have been resaved into your application will need to be refactored and modified. The effort is similar to adopting and using some of the new feature provided in a Pega release. Before upgrading to a new version of ui-kit, please review all the available documentation, videos and release notes provided on the Pega community. If you do not want to incur the development and testing cost of this ui-kit upgrade effort, you can keep using the same version of ui-kit. Each new release of the Pega Platform ships with all the version of the UI-Kit provided in previous releases.