Skip to main content


Using design templates to maintain consistent UI

4 Tasks

30 mins

Visible to all users
Beginner Pega Platform 8.5 Pega Platform 8.4 User Experience English


When designing a complex application, it is important to use consistent design patterns throughout the application. As such, it is important to convert your full section to use a design template. In this challenge, you look at a UI built with the full section editor and go through the process of upgrading a section to use a design template.

The following table provides the credentials you need to complete the challenge.

Role User name Password
Application Developer author@mytown pega123!


Challenge Walkthrough

You must initiate your own Pega instance to complete this Challenge.

Initialization may take up to 5 minutes so please be patient.

Detailed Tasks

1 Open the case manager portal and review recent lists

  1. In the App Studio navigation pane, click Preview application to access the Case Manager portal.
  2. Click New > Service Request to create a couple of Service Request cases.
  3. View the recent lists present in the lower-left corner of the Case Manager portal. The recent list uses a repeat dynamic layout and renders a list of recent items.
    Recent list in the case manager portal

    2 Convert the list item to use a design template

    Because the section is not using a design template, it is not possible to edit the section in App Studio. As a front-end developer, it is better to access the end-user portal from Dev Studio by opening the portal as a secondary portal and use liveUI to find the section that is used to render the list of recent items.

    1. Switch to Dev Studio and open the case manager portal as a secondary portal.
    2. Click the Toggle runtime toolbar icon and then click the Toggle Live UI icon to open the section.
    3. Open the section that is used to render the recent list itempyRecentWorkContent.
      Finding the section for the recent list item in Case manager using liveUI
    4. Navigate to the Dev Studio portal. This section uses a full section editor but can easily be converted to use the List Item with image, metadata, and action out-of-the-box template. Because this section is in a locked ruleset, the action to convert to a design template is being disabled.
      pyRecentWorkContent section shipped in ui-kit
    5. Do a Save As of the section to save this section into the application stack. Save the section in an unlocked ruleset of MyTown311:01-01-11 with the same Name and Apply to class.
    6. Click Create and open to open the section. Because the section is now in an unlocked ruleset, it is possible to click on the banner to convert the section to use a design template.
    7. Click Convert section to use a design template to convert the section. Confirm the action in the modal dialog. The section rule form will reload to render the UI used for managing the section using the design template.
    8. Click Save to save your rule changes.
    9. Click the Design tab.
    10. Click Change to select the right template.
      convert the section to use the to use a design template
    11. By default, the section will always use a One column design template.

      The conversion to design template does not automatically upgrade the section to use the right design template. It is the responsibility of the front end developer to convert the section and switch to the right design template (if it exists) or to create a new one. 

    12. For this use case, use the List Item with image, metadata, and action template.
    13. Move the fields to the right regions and save the rule
      pyRecentWorkContent after conversion to design template
    14. Go back to the Case Manager portal, refresh the browser, and review the changes made to see how the updated recent list looks like after these changes. While the list correctly renders the title and meta list, some items are missing padding on the left. Also, the highlighting of the row that occurred before is no longer working.

    3 Fix spacing issues

    1. Click View Properties on Dynamic Layout(Stacked) - 1 in the original section pyRecentWorkContent from UI-Kit ruleset. An aria role is set on the layout to be marked as a list widget and helper classes padding-lr-2x padding-tb-1x item-list-highlight are present under the Presentation tab of Content CSS class; it adds padding for top, bottom, and left.
      Added with aria role
      Remove the helper class which is added.
    2. The out-of-the-box list item design template is a generic template that does not provide any inner spacing for the content inside the list. To fix this spacing issue, click the Toggle runtime toolbar icon.
    3. Click the Toggle Live UI icon to open the section called pyRecents at class Data-Portal.
      open the section called pyRecents
    4. Do Save As of the section to save this section into the application stack.
    5. Save the section in an unlocked ruleset of MyTown311:01-01-11 with the same Name and Apply to class.
    6. Click Create and open to open the section.
    7. Click View Properties for the section included inside the Repeating dynamic layout-1.
    8. Click the Presentation tab.
    9. Select the Display advanced presentation options check box.
    10. Copy and paste the helper class padding-lr-2x padding-tb-1x item-list-highlight in both the Cell read-write classes and Cell read-only classes fields.
    11. Click Save.
      ​Cell Read-Write and Read-Only classes added with helper class
    12. Go back to the Case Manager portal, refresh the case manager portal, and confirm that the recent lists are now correctly rendered, and the row is highlighted on hover.
      recent list after changes using design templates
    13. Switch to App Studio and click the Case Manager portal by selecting the portal in the dropdown at the top. The new recent list based on the design template is rendered.
    14. In the header, click Design to highlight sections editable at runtime. The recent list item is now editable. It is possible to edit the properties inside the design template and add new properties if needed in App Studio.
      list items for recents is now editable in app studio

    4 Create a new design template

    The out of the box template list item with image, title, metadata, and actions is a good starting point, but for your design system, you might need a new generic template called List item with primary and secondary data. Doing so avoids exposing regions like Image and Actions that are not applicable for the recent list items and other lists.

    While you can customize the out of the box list item template, you might want to convert an existing section to be a design template. If you review the pyRecentWorkContent section, you see that this section can use a design template with two regions.

    regions that could be created to convert pyRecentWorkContent to use a design template
    Note: The two regions use Mimic a sentence; this format is used so that different properties render like a sentence with a spacing between word of 0.7rem. This is usually not the best approach for rendering properties of different types. A better approach is to use the inline middle format and use the item-separator helper class.
    1. Perform a Save As on the original section pyRecentWorkContent from the UI-Kit into your application stack.
    2. Change the rule Name to List item with primary and secondary data.
    3. Change the Apply To class to @baseclass so that this template is available to all sections and not just the ones under System-User-Recents.
      Creating the new design template at baseclass
    4. Click Create and open. Errors are reported because you are changing the Apply To class of the section.
      Errors reported after create and open due to the different apply to class
    5. Remove the four fields inside the two Dynamic Layouts (Mimic a sentence) – 1.1 and 1.2 and click Save. The errors should disappear.
    6. Click on the Settings tab.
    7. Select Design template.
    8. Select an icon image by searching as list and select webwb/pzImageMetadataActionsListIcon.svg.
      marking the section as using a design template
    9. Go back to the Design tab, open the property panel of the Dynamic Layout(Mimic a sentence) – 1.1.
    10. Select Use as template region.
    11. In the Region Name field, enter Primary.
    12. Open the property panel of the Dynamic Layout(Mimic a sentence) – 1.2.
    13. Check the setting Use as template region.
    14. In the Region Name field, enter Secondary.
    15. In the top-level Dynamic Layout(Stacked) – 1, remove the helper class under the Presentation tab because you moved them into the parent layout.
    16. Click the History tab and enter the description for the design template.
      Entering a description is important
    17. Save the section.
      section created as a new design template
    18. Switch to the section pyRecentWorkContent and change the template to use this new template; move the different properties to the correct region
      pyRecentWorkContent upgraded to use the new design template
    19. In App Studio, reload the Case Manager portal and confirm that the new recent item uses the new template.

    Available in the following mission:

    If you are having problems with your training, please review the Pega Academy Support FAQs.

    Did you find this content helpful?

    Want to help us improve this content?

    We'd prefer it if you saw us at our best.

    Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

    Close Deprecation Notice