View source for Theme Cosmos - Customizing Section-based Portals in App Studio

{{Design pattern
|E-mail notification sent=True
|Title=Theme Cosmos - Customizing section-based portals in App Studio|Description=Patterns for configuring Theme Cosmos portals in a section-based application.|Version=8.6|Applications=Pega Platform|Capability Area=User Experience|Owner=Vidya Menon
}}

When building a Pega Platform application on section-based Theme Cosmos, the default portal is the user portal. However, citizen developers can create new portals from the Channels area of App Studio. Once the basic portal is built, there might be a need to customize it based on specific needs. For example, certain users might only need to work on tasks assigned to them, while others need to access work queues and pick up tasks from a common pool. Yet another set of users might require customized landing pages that give them access to data beyond the scope of the out-of-the-box user portal. 

Users might also want to specialize their dashboards to have easy access to the data that they use most frequently. Apart from customizing the portal, citizen developers might want to customize specific details within a case to improve productivity.

Note that the screenshots used in this article might vary based on platform versions.

==Customizing the worklist gadget==
By default, the '''Home''' page in the user portal contains the '''My worklist''' gadget that allows users to pick up tasks assigned to them. In some cases, tasks are not assigned to specific users, but to work queues. In this way, any user with access to the work queue can pick up the task and work on it.

The following steps help you modify the worklist gadget to allow picking tasks from work queues in addition to tasks assigned to oneself.

1)    Log in to '''App Studio''' and click the '''Preview''' button in the top right corner. A '''Design''' icon appears.

2)    Click the '''Design''' icon to enter the Design mode.

[[File:Design mode.png]]

3)    Click the Pencil icon next to the main section to enter edit mode.

[[File:Design mode 1.png|alt=The editing pane is on the right side of the screen.|624x624px]]

4)    Click the '''Edit this section''' pencil icon next to '''HomeWorklist''' section.

[[File:Dm3.png|border|alt=Pencil icon is on the right side of the component name.]]

5)    Click the '''Settings''' link in the pane that opens.

[[File:Dm4.png|border|alt=The settings link is in the top-right of the editing pane.]]

6)    Notice two options as shown in the screenshot below. Click the checkbox next to '''Show team assignments in worklist''' to allow the user to pick assignments from work queues to which they have access. Click the '''Apply''' button on the top-right side and close the Edit pane.

[[File:Dm6.png|border|alt=General tab with Show team assignments and Display worklist as a table settings cleared.]]

The worklist gadget now provides a drop-down option to pick tasks from work queues as well.

[[File:Dm8.png|border|alt=Selector that allows the user to choose between individual tasks and work list tasks.]]

7)    By default, the user portal displays the worklist gadget as a repeating layout, as shown in first screenshot below. If you select the '''Display worklist as a table''' check box in step 6, the system converts the display into a table as shown in the screenshot below. You can choose the option you prefer.

[[File:List.png|border]]

[[File:Quu.png|border|alt=Work list formatted as a table.]]

== Customizing landing pages in the main menu ==
The user portal consists of landing pages that consolidate information for easy access. The landing pages are listed on the main menu. The default landing pages are: Create, Home, Dashboard, Spaces, Reports and Explore Data. If you want to add or remove certain landing pages from the main menu, follow the steps below.

1)    In '''App Studio''', click '''Preview''', and then click '''Design''' on the top-left side of the portal to enter Design mode.

2)    Click '''Pages''' on the top-left side of the Portal.

[[File:Custom.png|border|alt=List of available pages, including default pages like Home and Dashboard.]]

3)    Click '''New''' and provide a name for the new landing page.

4)    Click '''Edit Section''' pencil icon to add fields and sections to the new landing page. 

[[File:Newpage.png|border|alt=An empty new landing page.]]

Note that the Header and Content areas are separate sections and each one can be modified.

You can add any section available in the ''<AppName>-Portal-UIPages'' class to these landing pages. If a specific custom section needs to be added here, then it needs to be created in the '''Dev Studio''' in this class and marked as a relevant record. This way, it will be visible on the list of sections that you can include in the landing page from '''App Studio'''. Once the landing page is created, follow step 5 to include it in the portal main menu. 

Refer to this link on how to mark a record as relevant [https://community.pega.com/knowledgebase/articles/application-development/86/marking-records-relevant-records Marking records as relevant records | Pega].

5)    Along with the new pages created in '''App Studio''' in Step 4, any harness created in '''Dev Studio''' in the ''<AppName>-Portal-UIPages'' class and marked as a relevant record will also be visible under the '''Pages''' menu. You can now include it as a landing page in the main menu of the portal.

[[File:Upload.png|border|alt=Custom landing page being added to the main menu from the page list.]]

Click the '''three dots''' next to the landing page name and select '''Add to menu > Main menu''' to include the landing page in the portal. Clicking on '''Page settings''' allows you to change the icon associated with the landing page.

6)    Clicking on '''Remove from menu > Main menu''' allows you to remove any unwanted landing page from the portal. Newly added landing pages will be displayed as shown below.

[[File:LP.png|alt=List of landing pages in the main menu.]]

== Customizing the dashboard ==
Dashboards can be personalized for each user. To personalize the dashboard in '''App Studio''', enable Design mode, open the Dashboard landing page, and click '''Personalize''' '''the dashboard''' icon on the top right. This feature remains unchanged from how it was for applications using UI-Kit.

[[File:Dasbord.png|border]]

Refer to this link for more details on dashboard personalization.

https://community.pega.com/knowledgebase/articles/user-experience-theme-ui-kit/86/adding-widget-your-dashboard

== Customizing case display ==
A citizen developer can modify certain parts of how a case is displayed in the portal. Follow the steps below to modify basic case display details.

1)    In '''App Studio''', run the case type whose display details need to be modified. Click the '''Design''' icon to enter the Design mode.

2)    Click the '''pencil icon''' for the '''Preview''' section as shown below.

[[File:Pre.png|border|alt=The pencil icon is located in the header of the selected section.]]

The '''Preview''' section is divided into different areas, covering critical data (Top area that displays Status and Priority), primary case data, and additional details (which are empty by default).

[[File:Preview.png|border|alt=Preview section, divided into three areas, which are, top to bottom: critical data area, primary case data area, additional details area.]]

The edit pane on the left allows you to add fields to any of these three areas. Note that when you click the '''Add''' icon, you can only add the properties that are marked as relevant records for the case.

[[File:Leftside.png|border|alt=Case details with three data areas as visibile in the editor pane on the right side of the screen.]]

Click the '''Settings''' link and clear the check boxes to hide unwanted details like Priority, Status, etc. from the display screen, as desired.

[[File:Settings12.png|border|alt=All check boxes have been cleared.]]

3)    By default, a case created in an application built on Theme Cosmos comes with two tabs below the Preview area, namely Details and Pulse. To add new tabs, edit the '''Work area''' section in the Design mode.

[[File:Edit.png|alt=Work area that hosts tabs.]]

The Edit pane displays all the different areas of case display as shown below.

[[File:Title.png|border|alt=Edit pane lists template settings and fields included in the area.]]

Click '''Add''' icon in the '''Main''' content area and add a new section or include an existing section. If you need to create a new section, you can add fields to the section as shown below. Change the template by clicking on the '''Change''' button, and then select the '''Case information UI template''' which is best suited for Case details display.

Display details, like title, can also be modified under '''Container settings'''.

[[File:Xt.png|border|alt=Container settings section. The user is modifying the Title field.]]

Once you make these changes, the new tab will be visible for the case type as shown below.

[[File:Container.png|alt=Case page with the new Case details tab.]]

4)    In a similar fashion, sections can be added to the '''Utils''' area in the '''Work area''' section to include more utility widgets in the Utility pane.

[[File:Tcosmos.png|border]]

By default, Theme Cosmos applications include Files and attachments, Followers, and Stakeholder utility widgets.

5)    In '''App Studio''', open a case type, and click the '''Settings''' tab. Select '''Cosmos UI''' from the menu on the left side of the screen.

[[File:Mywork.png|border|alt=Cosmos UI settings in the Case type.]]

This screen provides you with the tools to customize certain aspects of the case UI. For instance, you can set up the display of case stages. By default, the to do list comes as a flat structure. When there are multiple child cases, hierarchical table might be a more user friendly display mode.

For more infromation, see https://community.pega.com/knowledgebase/articles/user-experience/86/managing-cosmos-ui-settings-case-designer.

6)    Select '''Collaboration''' menu under '''Settings''' tab and uncheck '''Enable tags''' to remove the Tags widget from the utility pane.

[[File:Uncheck.png|border|alt=Collaboration menu.]]

Similarly, clear the '''Enable follow''' check box to remove the Followers widget from the Utility pane.

[[File:Utility.png|border|alt=Sample utility pane with files and documents, followers, stakeholders, and tags widgets.]]



For additional details on organizing Portals, see [https://community.pega.com/knowledgebase/articles/user-experience/86/organizing-contents-portal Organizing Portal Content].