Extending an existing dashboard by adding new dashlets in the web UI framework

You can customize/extend an existing dashboard by adding dashlets.

About this task

Below is sample XML, with dashlet metadata definitions:


<Dashlets>
			<Dashlet id="dashlet_one" title="Dashlet One" type="html" tag="tag_1">
						<Url>/stk/dashboard/dashlet_one.jsp</Url>
						<Imgurl>/stk/img/dashboard/dashlet_one_preview.png</Imgurl>
						<Description>
									Dashlet one description bundle key
						</Description>
						<Config numberOfColumns="3">
						</Config>
			</Dashlet>
			<Dashlet id="dashlet_two" title="Dashlet Two" type="extscreen" tag="tag_2"
												multiInstance="true" refreshable="Y">
						<Url>/stk/dashboard/dashlet_two.jsp</Url>
						<Imgurl>/stk/img/dashboard/dashlet_two_preview.png</Imgurl>
						<Description>
									Dashlet two description bundle key
						</Description>
						<Config numberOfColumns="2">
						</Config>
						<!-- Other metadata relevant to the dashlet can be added based on type
						and url of the dashlet -->						
			</Dashlet>
			<Dashlet id="dashlet_three" title="Dashlet Three" type="html" tag="tag_3">
						<Url>/stk/dashboard/dashlet_three.jsp</Url>
						<Imgurl>/stk/img/dashboard/dashlet_three_preview.png</Imgurl>
						<Description>
									Dashlet three description bundle key
						</Description>
						<Config>
						</Config>
			</Dashlet>
</Dashlets>

Attribute and element descriptions for the above sample are given below.

id

A unique identifier of the dashlet. This id is used to query a dashlet and its properties. It is used by a dashboard definition to add a dashlet to it.

title

The title of the dashlet. It can be a bundle key which can be localized.

type

The type of the dashlet is a metadata about the type of content returned by a dashlet URL. By default, the Web UI Framework supports following types of dashlet:

HTML. Response of type HTML must be a valid HTML document fragment. Following examples illustrate various ways in which it can be used to render the dashlet UI: (1) A fully rendered HTML fragment that can be viewed in a browser without any further processing. (2) An iframe that can be used to safely embed widget from external websites. (3) A scriptlet that can dynamically render the content in the container.
extscreen. An extscreen is an ExtJS-based JavaScript UI rendering script. It can be used to render dynamic and interactive UI components.

tag

A comma separated value of tag names of the dashlet.

refreshable

Setting this value to Y makes the dashboard refreshable and a refresh icon is shown in the dashlet toolbox. When the refresh icon is clicked, the individual dashlet is refreshed.

multiInstance

Setting this to true would allow the dashlet to be added to the dashboard multiple times. This is an optional parameter and defaults to false.

URL

The URL used to get contents to render a dashlet. To render a dashlet into the dashboard, a request needs to be made to the server. The request is made to this URL and the response is rendered on the UI.

Imgurl

The URL to the image to be displayed showing a preview of the content displayed by the dashlet.

description

The description of the dashlet. It can be a bundle key which can be localized.

Config

The Config element is used to define configuration options used to render the dashlet on the UI. Some dashlets that do not require a configuration option may choose not to specify the Config element.

Note: In addition to the Config element, a dashlet can have other metadata elements. In general, the Config is used to define UI properties but it can be used to hold any kind of metadata.

To customize/extend an existing dashboard by adding dashlets, do the following:

Procedure

Create the new XML file for the dashlets, using the above sample code as a guideline.
Do one of the following:
- Navigate to the <<INSTALL_DIR>>/extensions/<app-name>/webpages folder. Create the desired directory structure and put your dashlet XML files here.
  The XML files defined here are copied to the <application-war>/extn/<your directory structure> folder.
- Navigate to the <<INSTALL_DIR>>/repository/eardata/<app-name>/extn folder. Create the desired directory structure and put your dashlet XML files here.
  The XML files defined here are copied to the <application-war>/<your directory structure> folder.

Create a new servlet to load your XML files and add them to the user dashboard.

Sample code:

//<dirPath> = <your directory structure> or extn/<your directory 
structure> depending on procedure used.
String appId = SCUIUtils.getApplicationId(config.getServletContext());
String dashletsFilePath = “<dirPath>/dashlets.xml";
InputStream isDlts = servletContext.getResourceAsStream(dashletsFilePath);
SCUIDashboardManager.getInstance(appId).registerDashlet(isDlts);

Package this servlet into a jar file and use the second method in case of a multi-war deployment. In other cases, you can use either method.
- Run the Install3rdParty.sh script from <<INSTALL_DIR>>/bin to include this jar file in the application.
- Navigate to <<INSTALL_DIR>>/repository/eardata/<app-name>/extn folder. Create the WEB-INF/lib folder. Copy the jar file here.
Navigate to the <<INSTALL_DIR>>/repository/eardata/<app-name>/extn folder. Make an entry in the web.xml file to load your servlet and ensure that it loads after your application initializer servlet by giving load-on-startup a value of around 1000 or greater.
Run the buildwar/buildear command.
On launching the application, your new dashlets would be loaded and you would be able to view them when you select the customize link on the dashboard.
Note: Existing dashboard config and layouts cannot be changed during dashboard extensibility. Only new dashlets can be associated for a dashboard.
Note: To add a dashboard to an application, similar steps need to be followed. Below is sample XML, with dashboard metadata definitions:
```
<Dashboards>
   <Dashboard id="myhomepage" title="My Homepage" tag="tag_1,tag_n"
              version="0.0.1">
      <Config> 
         <Layouts currentLayoutId="twoEqualColumn">
            <Layout id="twoEqualColumn" type="column"
                    previewIconUrl="/stk/img/dashboard/2col_preview.png">
               <Column id="d_one" width=".49"/>
               <Column id="d_two" width=".49"/>
            </Layout>
         </Layouts>
      </Config>
      <Dashlets>
         <Dashlet id="dashlet_one" parent="d_one" >
         </Dashlet>
         <Dashlet id="dashlet_two" parent="d_two">
            <Config numberOfColumns="1" >
            </Config>
         </Dashlet>
      </Dashlets>
   </Dashboard>
</Dashboards>
```
id

A unique identifier of the dashboard. This id is used for checking resource permissions and authorization. If a dashboard contains a dashlet for which the user does not have the permission, that dashlet will not be shown to the user.

title

The title of the dashboard. It can be a bundle key which can be localized.

tag

A comma separated value of tag names of the dashboard. These tags are used to find dashlets having matching tags. These related dashlets are available when you customize the dashboard.
Note: You will be able to see other tags also, but by default, only dashlets with matching tags will be displayed.

version

The dashboard metadata version. It can be used in case of multi-tenancy to support different versions of dashboard metadata.

Config

The Config element is used to define configuration options used to render the dashboard. One such configuration option is the layout of dashlets in a dashboard.
Layouts are used to define layout strategies supported by a dashboard. It contains child elements defining individual layout strategies. Currently, only a column layout is supported as a standard layout of dashboard.

Dashlets
A list of all the dashlets to be displayed in the dashboard. Each dashlet can have following set of attribute and elements:

id. Reference id of the dashlet to be added to the dashboard.

Parent. The layout container id in which the dashlet will be added.