Preflight Optimization: Finding CSS not detected during optimization and fixing it
Since Preflight Optimization is a design time optimization, there are situations when the specific classes that are used to represent some aspects of the user interface are not known until run time. When this happens and preflight optimization has been turned on, some classes associated with objects in the model that are only determined at run time may not be included in the design time optimizations. In this document, we show some cases where out-of-the-box Express apps exhibit this behavior and how the Preflight Optimization Advanced tab can be used to force ("whitelist") the inclusion of these run time classes. We also present some hints on how to refer to the browser DOM to find the classes to help customers find and fix similar issues in their Pega applications.
Which Express apps require whitelisting to make sure classes only known at run time are included during Preflight Optimization?
All 3 of the primary Express application types:
What needs to be whitelisted?
Since an application's Preflight Optimization is performed separately depending on the target Portal, the classes that need to be noted depend on which Portal is being optimized.
For the User portal:
Rule Type: Section – Applies to: Assign-Worklist – Name: pyCaseContentDetails
For the Manager portal:
Rule Type: Section – Applies to: Data-Portal – Name: pyWelcomeToPegaCaseManager
Rule Type: Section – Applies to: Data-Portal – Name: pyCaseManagerShortcuts
Why do these sections need to be whitelisted?
Since the Preflight Optimization is a design time optimization, there are cases when the specific classes that are used to represent some aspects of the user interface are not known until run time. When this happens and preflight optimization has been turned on, it can result in some classes associated with objects in the model being used at run time that have not been included in the design time optimizations. In the case of the 3 sections listed above, each of the Sections that need to be whitelisted are not associated with a specific class until run time. Therefore, we need to add them to the Preflight Optimization whitelist in order for the model analyzer to make them as being used.
How do I whitelist these sections?
When creating a Preflight Optimization, you can add specific items to be whitelisted on the Preflight Optimization Advanced tab. (You can also “blacklist” items by entering them on the Advanced tab and checking the “Skip” checkbox.)
To properly whitelist the Section needed for the User portal, you can enter the information above in the Advanced tab as shown here:
To properly whitelist the Section needed for the Manager portal, you can enter the information above in the Advanced tab as shown here:
What happens if these Sections are NOT Whitelisted?
In the User portal, when creating a new case (below, we show the creation of Service Request), the Open Assignments detail is improperly rendered. The text is shifted over to the right and the “clock” icon is in the wrong place relative to the text as shown here toward the right of the screen:
In the Manager portal when viewing the Dashboard, the Tour video and Welcome panes are incorrectly stacked and the Case Manager shortcut icons are improperly rendered as shown here in the top middle and right of the screen:
How will these Sections be displayed when they have been properly whitelisted?
When properly whitelisted, the CSS optimization will have loaded all of the CSS necessary to render the sections. Therefore, these sections will be rendered exactly as they are rendered when the application does not have CSS Optimization turned on.
In the User portal, the Open Assignments text and “clock” icon will appear properly placed as shown here:
In the Manager portal, the Tour Video and Welcome to Pega 7 sections will be shown side-by-side. Similarly, the Case Manager Shortcuts will be properly rendered. Both of these are shown here:
How can I find and fix similar CSS Whitelisting opportunities in my applications?
If you encounter other Sections (or UI objects) in your applications that seem to have been missed by the CSS Optimizer since the class assignment wasn’t known at design time, you can inspect the page’s elements (using your browser’s DOM Inspector) to see where the problem likely was encountered. If we look at the “Get next work” improper rendering in the Manager portal, we can use the DOM Inspector to see where the appropriate “Get next work” is found. Then, if you read up the DOM structure, you can find the closest enclosing Section. In that markup, you can find that the text is in the Rule-HTML-Section (so we know this is a section) with the node_name of pyCaseManagerShortcuts and a pyClassName of Data-Portal. Note that these map directly to the Section – Data-Portal – pyCaseManagerShortcuts that we entered in the Advanced tab to whitelist the section. You can see a sample, annotated markup here: