Best practices to consider while using Pega modals/overlays
1. How to configure a modal dialog / overlay? What are the default and custom configurations?
Overlays can be configured through Local action whereas modal dialogs can be configured through 2 actions - Local action, Flow in a modal dialog. Default config: On adding local action with the target as a modal dialog, by default "Standard" format is selected along with modal template pzModalTemplate of the parent class. On mobile the modal displays as a full screen by default. If we uncheck the checkbox "Display as full screen on a mobile device" the modal appears with a masked background like in desktop. Apart from this, we have configurations to animate the modal reveal/dismiss on desktop as well as mobile.
Default configuration Modal animation configuration
Default mobile view of modal dialogs
2. Which format of modal dialog should I use?
| Standard | Full Screen | Fixed Sized | |
|---|---|---|---|
| Size | The size of the modal is not fixed and varies depending on the content inside modal | The minimum size of the modal is fixed to 95vh x 95vw. The modal may grow more ( and almost cover the entire screen ) if the modal content is more. | The size of the modal is fixed to 650 x 600px |
| V.Scroll | The vertical scroll is added to the page if the browser window is smaller than the page contents. Also, there is a vertical scroll that gets added to the content of the modal keeping the header and footer sticky. | The vertical scroll is added to the page if the browser window is smaller than the page. There is a vertical scroll that gets added to the content of the modal keeping the header and footer sticky. | The vertical scroll is added to the page if the browser window is smaller than the page. In case the content is more than 600px in height, the vertical scroll gets added on the entire modal including the header and footer. |
| H.Scroll | The horizontal scroll gets added to the page in case the modal width is larger than the window width. | The horizontal scroll gets added to the page in case the modal width is larger than the window width. | The horizontal scroll gets added to the page in case the modal width is larger than the window width. |
| Area of use | This format should be used anywhere where there is no restriction on the modal size and the modal should take its size depending on the contents. This is the default format mostly being used all across like Property Panel, Check-in, Private edit, and many more | This format should be used where there is huge data to be presented on screen. This is currently used in data mapping screens where there is a lot of data and requires the user to draw mappings from one panel to another. | This is suggested to be used across models with tabbed navigation of 3 or more tabs, thus keeping the height of the modal fixed even on switching tabs of different content heights. |
|
|
|
3. Which is the recommended modal and overlay template to be used?
Make use of the OOTB pzModalTemplate (Rule- ) with your suitable modal format. pzModalTemplate (Rule-) has already been optimized and can be referred to. Do not make modifications to pzModalTemplate (@baseclass) as it is being used all across applications and may affect many other existing modals. For overlays, make sure to use the pyOverlayTemplate (Rule -).
4. How can we configure or customize the modal header and footer?
While adding modal through "Local action" or "Flow in modal dialog", we call a flow action which in turn contains a section. This section only has the content of the modal. The modal header and footer are generated from the modal template that we add in the configuration.
- To manipulate the header title - Change the flow action name. This name is localizable hence can contain a localized name corresponding to the field value.
- To manipulate the footer - In the flow action we have options to hide the footer button or change the footer action buttons names
- To change the footer button labels use "Customize the action section button labels" to provide required footer button labels.
.
Customize action buttons
5. What if the recommended template does not suit my requirements?
Go for other modal templates only if required. Ex :
- There is supposed to be visibility condition on the modal title -
For certains sections we may have to configure the modal using other than the recommended template because the flow action refers to section having a visibility condition to show or hide the modal title. Because this title is not constant hence we cannot directly modify the flow action title.
- The modal title has some dynamic content that cannot be localized directly using a field value.
For certain cases, there may be a nesting of properties that cannot directly be used as a field value.
6. What should be the proper structuring of templates?
- No nested DLs
. 
- Optimised layouts
. 
- Proper use of helper classes
7. What is the suggested look and feel of a modal dialog?
- Modal cross button should be present on top right on the header
- Modal should consist of header, content, footer sections
- Modal should not close on clicking outside unlike overlays
- Modal should always have a mask (currently we have a dark page background ) when it's open
- Modal content should scroll if the modal size gets smaller than the window size
8. When should I use modal/overlay?
If the content to be shown is small and read-only kind of content we should go with overlay. If the content is large enough and has a proper action set associated we should prefer to use modal dialogs. Overlays can be dismissed easily by clicking anywhere on the screen (outside the overlay), hence it may not be able to catch user attention, so we recommend modals to be used at places where we need to catch user attention. We cannot launch a modal on top of a modal but we can open overlay on top of an overlay and modal.
9. What are the Pega UX guidelines for spacing in modal ?
- Header - Padding on all sides except bottom - 14px , Padding on bottom - 7px , No margin
- Content - Padding on all sides - 14px , No margin
- Footer - Padding on all sides - 14px , No margin
- Close button - Icon size 20 x 20
- Modal title text - 16px Open Sans , font weight - 600
- Primary action button - Strong button format
- Secondary action button - Simple button format
- Primary action button to be positioned at the right end of footer
- Modal footer background should be the same color as content