64 Contributor Interface: Customizing the Dashboard

This chapter describes how to customize the dashboard of the WebCenter Sites Contributor interface. It familiarizes you with the dashboard configuration and provides sample code, which you can use while you perform the procedures described in this chapter.

This chapter contains the following topics:

Section 64.1, "Overview of Dashboard Customization"
Section 64.2, "Customizing the Dashboard"
Section 64.3, "Examples of Customizing the Dashboard"

64.1 Overview of Dashboard Customization

When you log in to the Contributor interface, the dashboard is displayed. By default, the dashboard displays the following ready-to-use widgets: Bookmarks, SmartLists, Checkouts, and Assignments, as shown in Figure 64-1.

Figure 64-1 Dashboard with Default Widgets

Description of "Figure 64-1 Dashboard with Default Widgets"

You can customize the following portions of the dashboard and its widgets:

Number of columns
Column width
Widget's display name, height, and position on the dashboard
You can also add new widgets.

64.2 Customizing the Dashboard

The system-defined dashboard is generated by the controller element UI/Layout/CenterPane/DashboardContentsConfig. You can override this element.

Your dashboard configuration can be global or site-specific. You can customize the default widgets, add new widgets, and delete the ones not required.

To customize the dashboard

Override the element UI/Layout/CenterPane/DashBoardContentsConfig by creating your own DashBoardContentsConfig.jsp under CustomElements and customizing its properties.

Note:

When a new widget is added or an existing widget is updated, you must clear user preferences in the WEM UI for the changes to take place.

The UI/Layout/CenterPane/DashBoardContentsConfig element is shown next, followed by property descriptions in Table 64-1.

Element UI/Layout/CenterPane/DashboardContentsConfig

<dashboardconfig>
   <dashboardlayout>
      <numberofcolumns></numberofcolumns>
      <columnwidths></columnwidths>
   </dashboardlayout>
   <components>
      <component id="widgetId"> 
         <name>widgetName</name>
         <url>widgetURL</url>
         <height>height_in_px</height>
         <dragRestriction>true | false </dragRestriction>
         <column>number_of_column_in_which_to_display_widget</column>
     </component>
         …
         … 
         …
   </components>
</dashboardconfig>

Table 64-1 Properties in UI/Layout/CenterPane/DashBoardContentsConfig.jsp

Property	Description	Value
`<numberofcolumns>`	Number of columns in the dashboard display.	Integer greater than 0. The system default is `2`.
`<columnwidths>`	Comma-separated widths of columns.	For example, if there are `3` columns in `<numberofcolumns>` then the `<columnwidths>` can be `30,30,40`.
`<components>`	This section is used to define dashboard widgets.	N/A
`<component>`	Used to define a single widget.	N/A
`<id>`	ID of the widget.	Alpha-numeric value unique across widgets. Special characters are not allowed.
`<name>`	Displayed name of the widget.	Arbitrary string.
`<url>`	Controller URL.	The file location of the widget in the `UI/Layout/CenterPane/DashBoard/<Your_Element>`/ directory.
`<height>`	Height of the widget.	Height in pixels. For example, `300px`.
`<dragRestriction>`	Restricts dragging of the widget.	`true \| false`
`<column>`	The column in which the widget is displayed.	`1` to `n` , where n is the value specified in `<numberofcolumns>`.

64.3 Examples of Customizing the Dashboard

You can add new widgets to the WebCenter Sites Contributor dashboard. Adding a new widget involves two basic steps:

Creating the widget element.
Registering the new widget in your custom DashBoardContentsConfig.jsp element.

This section illustrates the process of adding a widget to the dashboard. This section contains the following examples:

Section 64.3.1, "Adding a 'Hello World' Widget"
Section 64.3.2, "Adding a Widget that Shows Recently Modified Assets"

64.3.1 Adding a 'Hello World' Widget

In this section, you will create and register a simple widget, shown in Figure 64-2.

Figure 64-2 'Hello World' Widget

Description of "Figure 64-2 'Hello World' Widget"

To add your widget to the dashboard

Create your widget:
1. Create a JSP element under CustomElements. In this example, we name the element HelloWorldHtml.
2. For widget code, you can navigate to the sample file provided with this guide and copy its content.
Register your widget (add it to the dashboard):
1. Open your custom DashBoardContentsConfig.jsp, locate the <components> section, and add the newly created widget's specifications. For example:
```
<component id="helloworld">
  <name>Hello World</name>
  <url>Path_to_your_widget_under_CustomElements</url>
  <height>300px</height>
  <closable>false</closable>
  <open>true</open>
  <dragRestriction>true</dragRestriction>
  <style>checkoutPortlet</style>
  <column>2</column>
</component>
```
2. Go to the <applicationServer_install_directory>/webapps/<cs_context>/WEB-INF/classes/ReqAuthConfig.xml file and add the path to the sample element, under the excludedControllerElements list. In our example, the path is:
```
<property name="excludedControllerElements">
   <list>
       <value>/UI/Layout/CenterPane/DashBoard/HelloWorld</value>
   </list>
</property> 
```
3. Refresh the home page of your Contributor interface. The new widget is displayed on your dashboard (Figure 64-2).

64.3.2 Adding a Widget that Shows Recently Modified Assets

In this section, you will create a widget that shows which assets were modified in the past week. After completing the steps in this section, your dashboard will display a widget similar to the one in Figure 64-3.

Figure 64-3 'Recently Modified Assets' Widget

Description of "Figure 64-3 'Recently Modified Assets' Widget"

To add your widget to the dashboard

Create your widget:
1. Create an Action JSP element under CustomElements. In this example, we name the element RecentlyModifiedAssetsAction.jsp. For the widget code, you can navigate to the sample file provided with this guide and copy its content.
2. Create a Json JSP element for the Action element created in the previous step. In this example, we name the element RecentlyModifiedAssetsJson.jsp. For the code, you can navigate to the sample file provided with this guide and copy its content. Place the element in the same location as the RecentlyModifiedAssetsAction.jsp element.
3. Create a presentation element under CustomElements for your widget. Name the element after the widget element. In this example, we name the display element RecentlyModifiedAssetsHtml.jsp. For the code, you can navigate to the sample file provided with this guide and copy its content.
  
  Note:
  
  The presentation element will call the RecentlyModifiedAssetsAction.jsp element. Enter the path to that element.

Open your custom DashBoardContentsConfig.jsp, locate the <components> section, and add the newly created widget's specifications. For example:

<component id="myrecent">
<!-- a unique identifier for the component. This must be unique among all the components. It can be alpha numeric but no special characters allowed --> 
      <name>Recently Modified Assets</name>
      <url>Path_to_your_custom_widget's presentation_element</url>
      <height>300px</height>
      <closable>false</closable>
      <open>true</open>
      <dragRestriction>false</dragRestriction>
      <style>checkoutPortlet</style>
      <column>2</column>
</component>

Go to the <applicationServer_install_directory>/webapps/<cs_context>/WEB-INF/classes/ReqAuthConfig.xml file and add the path to the sample element, under the excludedControllerElements list. In our example, the path is:
```
<property name="excludedControllerElements">
   <list>
      <value>/UI/Layout/CenterPane/DashBoard/RecentlyModifiedAssets</value>
   </list>
</property> 
```
Refresh the dashboard to see the newly configured widget. For example, see Figure 64-3.