Creating your own Dashboard Designer Template

Skip to end of metadata
Go to start of metadata

How to make your own Dashboard Designer Template.

In the Pentaho BI Suite 3.0 Enterprise Edition, there is a new utility included in the Pentaho User Console, the Dashboard Designer. Please note that the Dashboard Designer is part of the EE version of the Pentaho BI Suite only and is not in the Community Edition. The DBD allows non-technical users to layout Pentaho content in a Template and Theme based approach. Included are a number of Themes and Templates that you can choose from to layout and style your own dashboards. However if these do not meet your needs, it is relatively simple to create your own.


 
 
To create your own Template, you must locate the "templates" directory under your Pentaho installation. (Please note that the directory structure will be the same no matter what O/S you are using.)

..\pentaho\server\biserver-ee\pentaho-solutions\system\dashboards\templates.

Here you will see an "html" and a "xul" (pronounced "zool") folder. Open the xul folder.There will be a set of files with file names such as 01-2-by-2.*.  The first number attribute is just a sequence number, you will notice that it increases with each template set in the folder; the descriptive text follows next along with the dashes. Make sure when you create your templates you increment the first part of the file name to coincide with the number of templates you have in this directory.


 
The set of files will be in the form of a .xul file, a .properties file and a .png file.  The .properties file has the display name of the template, the .xul file is the template definition, and the .png is the template image thumbnail displayed in the DBD when selecting a Template from the Template list.

First you will want to copy all three files of one particular set, for example select the existing 05-1-over-2.* file set. That will be 05-1-over-2.png, 05-1-over-2.properties and 05-1-over-2.xul. With these three files selected copy and paste them, and then rename them to some name describing a template  that you will want to use ,such as 13-3-over-3.  (keeping in mind to auto increment the first part of the file name.) For this example, I already have 12 templates so I renamed the new set to 13-3-over-3. Now I have a new file set, 13-3-over-3.properties, 13-3-over-3.xul and 13-3-over-3.png. Now that I have my 3 new files I must do 3 things to create my new template:

  1. Edit the .properties file to add a descriptive name such as "3 over 3"
  2. (which is  not covered in this tech tip) edit the .png using some graphic manipulation software to create the thumbnail display image  that will represent your new template
  3. Edit the .xul file with a text editor using the appropriate syntax

We will cover step (3) here, but first we want to make sure that the new template will be displayed in the DBD. Make sure your Pentaho BI Server is started and that your browser cache has been cleared.

  1. Log on to the Pentaho User Console as an Admin user such as Joe
  2. In the Tools menu, select Refresh System Settings and then Refresh Plug-ins
  3. Close all corresponding message windows that open.

Start the DBD, you should see your new template in the list. Keep in mind if you did not change your thumbnail image, it will look like you have a duplicate of another template.


 
Next, if you select it you can see the template displayed for the new Dashboard you are creating, however it will not yet represent what you want.

Now it is time to edit the .xul file with a text editor.

The process of editing the file is as simple as cutting and pasting blocks of code and editing the appropriate label and sizing parameters. For this example I chose to create a 3 over 3 template using percentages with the "flex" attribute.  You can use pixel(height /width) and/or percent (flex) to control the layout's, box's and panel's size. Use the "flex" attribute for percentages, meaning the boxes/panels will auto size based on the size of the screen, use "height" and "width" properties to use pixel perfect absolute based sizing and positioning.

The following is an example that uses both "flex" and "height" and "width" attributes for a fixed 3 over 2 style layout.

<?xml version="1.0"?>
<window id="Dashboard" xmlns:pho="http://www.pentaho.com"    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <box id="FilterPanel" pho:type="povpanel" height="38" hidden="true">
        <hbox id="FilterPanel content" pho:type="layout">
        </hbox>
    </box>
    <vbox id="widget-area" pho:type="scrollarea" flex="45">
        <hbox id="hbox1" pho:type="layout" height="470">
            <box id="Panel_1" pho:type="titled-panel" pho:title="${widget1}" width="480">
                <vbox id="Panel 1 content" pho:type="layout">
                </vbox>
            </box>
            <box id="Panel_2" pho:type="titled-panel" pho:title="${widget2}" width="510">
                <vbox id="Panel 2 content" pho:type="layout">
                </vbox>
            </box>
            <box id="Panel_3" pho:type="titled-panel" pho:title="${widget3}" width="250">
                <vbox id="Panel 3 content" pho:type="layout">
                </vbox>
            </box>
        </hbox>
        <hbox id="hbox2" pho:type="layout" height="420">
    <box id="Panel_4" pho:type="titled-panel" pho:title="${widget4}" width="770" height="330" >
                <vbox id="Panel 4 content" pho:type="layout">
                </vbox>
            </box>
        <box id="Panel_5" pho:type="titled-panel" pho:title="${widget5}" width="470" height="190">
    <vbox id="Panel 5 content" pho:type="layout">                            </vbox>           
</box>
    </hbox>
    </vbox>
</window>
 

Now, here is the existing code of the template that we copied, we will now modify this to make our own template.

<?xml version="1.0"?>
<window id="Dashboard"
    xmlns:pho=http://www.pentaho.com
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <box id="titlebar" pho:type="pagetitle" height="20" hidden="false">
    </box>
    <box id="FilterPanel" pho:type="povpanel" height="38" hidden="true">
        <hbox id="FilterPanel content" pho:type="layout">
        </hbox>
    </box>
    <vbox id="widget-area" pho:type="scrollarea" flex="100">
        <hbox id="hbox1" pho:type="layout" flex="50">
            <box id="Panel_1" pho:type="titled-panel" pho:title="${widget1}" flex="100">
            <vbox id="Panel 1 content" pho:type="layout">
            </vbox>
        </box>
        </hbox>
        <hbox id="hbox2" pho:type="layout" flex="50">
            <box id="Panel_2" pho:type="titled-panel" pho:title="${widget2}" flex="50">
                <vbox id="Panel 2 content" pho:type="layout">
                </vbox>
            </box>
            <box id="Panel_3" pho:type="titled-panel" pho:title="${widget3}" flex="50" >
                <vbox id="Panel 3 content" pho:type="layout">
                </vbox>
            </box>
        </hbox>
    </vbox>
</window>

Here is the modified code below. Take note to the lines copied and the differences in the attributes. (names and sizes)
The numbers add up to 100% (or 99) - the names of the panels and the Widget areas are just auto incremented respectfully.

<?xml version="1.0"?>
<window id="Dashboard"
    xmlns:pho="http://www.pentaho.com"    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <box id="titlebar" pho:type="pagetitle" height="20" hidden="false">
    </box>
    <box id="FilterPanel" pho:type="povpanel" height="38" hidden="true">
        <hbox id="FilterPanel content" pho:type="layout">
        </hbox>
    </box>
    <vbox id="widget-area" pho:type="scrollarea" flex="100">
        <hbox id="hbox1" pho:type="layout" flex="50">
            <box id="Panel_1" pho:type="titled-panel" pho:title="${widget1}" flex="33">
            <vbox id="Panel 1 content" pho:type="layout">
            </vbox>
            </box>
            <box id="Panel_2" pho:type="titled-panel" pho:title="${widget1}" flex="33">
                            <vbox id="Panel 2 content" pho:type="layout">
                            </vbox>
            </box>
            <box id="Panel_3" pho:type="titled-panel" pho:title="${widget1}" flex="33">
                            <vbox id="Panel 3 content" pho:type="layout">
                            </vbox>
            </box>
        </hbox>
        <hbox id="hbox2" pho:type="layout" flex="50">
            <box id="Panel_4" pho:type="titled-panel" pho:title="${widget4}" flex="33">
                <vbox id="Panel 4 content" pho:type="layout">
                </vbox>
            </box>
            <box id="Panel_5" pho:type="titled-panel" pho:title="${widget5}" flex="33" >
                <vbox id="Panel 5 content" pho:type="layout">
                </vbox>
            </box>
        <box id="Panel_6" pho:type="titled-panel" pho:title="${widget6}" flex="33" >
                <vbox id="Panel 6 content" pho:type="layout">
            </vbox>
            </box>    
</hbox>
    </vbox>
</window>

To see your changes after editing the code and saving it, in the Dashboard Designer just simply select another template and then reselect the template you are editing to enable the new change. You will see the change reflected in the dashboard view. You can repeat this process as many times necessary until the desired template is created.

 

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.