You can create dashboards by using the Web user interface (UI) of IBM® Rational Team Concert™. You define a new dashboard and configure it by choosing which viewlets you want to include from the Viewlet Selector, or you can create a dashboard from a template as this article explains. Each viewlet shows information about some aspect of a project, team, work items, builds, and so forth. Viewlets are defined in code and contributed by extension points. This article focuses on creating personal dashboards with custom viewlets. It describes how to customize a viewlet programmatically by using JavaScript and calling REST services and Dojo widgets that you might want to include in the viewlet.

Create a personal dashboard and add custom viewlets

1. Navigate to the Web UI for Rational Team Concert on Jazz (https://localhost:9443/jazz/web), select the Dashboard page, and click Create Dashboard on that page (See Figure 1).

2. Make sure that you have permissions set for Create and Save Dashboards in the Project Configuration Permissions (Figure 2).

3. Click the Add Viewlet button on the extreme right of the Dashboards page.

Note:
If the dashboard appears but doesn't have an Add Viewlet link, it means that the user that you are logged in as doesn't have permission to modify the dashboard. You will need to launch the Eclipse Rich Client Platform (RCP) client, log in to your local repository as an admin, and update the permissions in the process specification tab of the project area editor.

4. Choose the viewlet that you want to add to your dashboard and click Add Viewlet (Figure 4).
5. Then close this dialog window.

The viewlet will now be on your dashboard.

Back to top

Alternative: Create the viewlet programmatically

These steps outline what is required to declare a plug-in as a Web bundle. Upon completion, the plug-in will not actually contribute anything to the Web UI, but it will place resources on the server to ensure that it is working correctly.

Create a plug-in to hold the viewlet

Configure plug-in project

<!-- Web bundle marker -->
<extension point="net.jazz.ajax.webBundles">
    <prerequisites>
        <requiredWebBundle id="net.jazz.ajax"/>
        <requiredWebBundle id="net.jazz.web.ui"/>
    </prerequisites>
</extension>

<!-- Viewlets and categories -->
    <extension point="com.ibm.team.dashboard.common.viewlets">
        <category id="com.ibm.afworkpktmgmt.category" name="AFWorkPacketMgmtViewlet">
        </category>
        
        <Viewlet icon="graphics/icons/icon.gif" 
        id="com.ibm.afworkpktmgmt.viewlet" refresh-interval="15" 
        title="Application Factory Work Packet Management" 
        widget="com.ibm.af.workpktmngmt.viewlet.web.ui.internal.AFWorkPacketMgmtViewlet">
        </viewlet>
        
        <viewlet-entry        category="com.ibm.afworkpktmgmt.category"
        title="Application Factory Work Packet Management"
        preview="graphics/images/preview-AFWorkPktMngmtViewlet.PNG"
        viewlet-id="com.ibm.afworkpktmgmt.viewlet">
        <description>
            This is the description of the AFWorkPacketMgmtViewlet entry 
            that appears in the viewlet chooser.
        </description>
        </viewlet-entry>

    </extension>

The Web bundle marker extension simply declares that this bundle has Web UI code. The Web UI code requires this in order to know which bundles to scan for code, the CSS, and so forth.

category: This is for the AFWorkPacketMgmtViewlet" root node in the Viewlet Selector (shown in Figure 4). The name is the label and the id is a language-neutral identifier that can be used to refer to this category.

viewlet: his is the viewlet definition (implementation). This is not the entry that shows up in the chooser (that's the viewlet-entry); it is the back-end code associated with the entry. The widget attribute is the name of the viewlet class in JavaScript that implements the viewlet logic. It's just like a fully qualified Java™ class name, except that it's a custom Dojo widget.

viewlet-entry: This is the entry that appears in the chooser. The viewlet ID points to the viewlet element, and the category points to the category element to link everything together. The preview and description are presented inside the Viewlet Selector.

Viewlet implementation (JavaScript)

Previously, in the plugin.xml file, the viewlet implementation pointed to this class:

com.ibm.af.workpktmngmt.viewlet.web.ui.internal.AFWorkPacketMgmtViewlet

This corresponds to the file in this path:

com.ibm.af.workpktmngmt.viewlet.web /resources/ui/internal/ AFWorkPacketMgmtViewlet.js

The resources segment is a special folder in Web bundles that contains all of the Web resources, and the internal segment is used to signal internal (non-API) code so that other developers don't create any dependencies on this code.

The package structure for this plug-in would be somewhat like the one in Figure 5.

The JavaScript (.js) file begins with the dojo.provide statement to make this Dojo accessible:

dojo.provide("com.ibm.af.workpktmngmt.viewlet.web.ui.internal.AFWorkPacketMgmtViewlet");

To be able to extend the base class viewlet (this is analogous to an import statement in Java):

dojo.require("com.ibm.team.dashboard.web.ui.Viewlet");

To allow you to use short form names, as in Java™ technology, you declare an alias, which is a local variable that points to the full class name wrapped in a function (see Listing 2). This is to ensure that this local variable doesn't conflict with anything in the global namespace.

function() {
var Viewlet = com.ibm.team.dashboard.web.ui.Viewlet;
dojo.declare("com.ibm.af.workpktmngmt.viewlet.web.ui.internal.AFWorkPacketMgmtViewlet",
        Viewlet, {
constructor: function() {

                        this._widget = null;
    
    
            },

templatePath: dojo.moduleUrl("com.ibm.af.workpktmngmt.viewlet.web", 
"ui/internal/templates/AFWorkPacketMgmtViewlet.html"),
//functions related to events on the viewlet
});

})();

The dojo.declare statement declares the widget with the second parameter as Viewlet, the alias of the base class that it extends.

The template path is the path to the HTML file for this template-based Dojo widget which contains HTML code to be rendered on this viewlet.

Template file

The HTML template file serves as the design template for the presentation of the widget (in this case, your dashboard viewlet), as Listing 3 shows.

<div class="com-ibm-af-workpktmngmt-viewlet-web-ui-internal-AFWorkPacketMgmtViewlet">
<b> Work Packet Templating </b><br>
<a href=#  dojoAttachEvent="onclick: _exportAFOnClick">Export Factory WorkItems</a><br>
</div>

This could be a sample template that renders a link called "Export Factory WorkItems. This is the fully qualified CSS class name to scope it to only this viewlet:

com-ibm-af-workpktmngmt-viewlet-web-ui-internal-AFWorkPacketMgmtViewlet 

We have a special link that runs the script rather than linking to an HREF tag: (href=#).

The dojoAttachEvent is the Dojo Toolkit way of connecting the event and the handler. When it is clicked, it will call the given function on the appropriate viewlet instance with a properly scoped value.

The CSS file is also scoped to this viewlet by writing the fully qualified class name for each style.

The CSS is picked up as the CSS optimizer scans all Web bundles for any .css files and includes it in the styles that are sent to the browser. Here is an example of the contents of a .css file:

.com-example-star-widget .star {
    width:auto;
    height: 20px;
        position: relative;
        left: 4px;
}

The template file can also contain Dojo attach points to have a link to the JavaScript file for Dojo components to be added. This template would then truly serve as a design template, just to align all of your Dojo components. Listing 4 shows an example.

<div>

<table cellspacing="12">

    <tr>
        <td>
    
            <B>Project Area :</B>    
    
    </td>
    
    <td dojoAttachPoint='projectAreaListBox'>
            </td>
    </tr>
</table>
</div>

The JavaScript (.js) file would add widgets to the projectAreaListBox dojoAttachPoint as Listing 5 shows.

this.projectAreaButton = new dijit.form.Button({

         id:  projectAreaButton",
        
            label: "Project",
            
         });
   
this.projectAreaListBox.appendChild(this.projectAreaButton.domNode);

Calling REST services from the viewlet

The viewlet might have components or might need to call REST services (see Listing 6) to get data either by sending certain parameters or by submitting a form.

var handler = {
                _success: function(done){
                    
                    console.log("success  + done);
                    }
                   
               
                },

                _failure: function(done){
                    console.log("failure  + done);

                    
                }

            };
            
     var srh = new ServiceResponseHandler(handler, "_success", "_failure");

         var reqParms= {
        
            param1: value1,
            param2: value2,
            };

        var serviceRequest = 
        new ServiceRequest("com.ibm.af.template.common.IAFTemplateService", 
        "postImportWorkItems",reqParms );

TeamServerClient.invokeService(serviceRequest, srh);

Where com.ibm.af.template.common.IAFTemplateService is the interface for the service, postImportWorkItems is the method to be called with the mentioned Request Parameters.

These variables should be declared in the ,js file (see Listing 7).

var ServiceRequest = com.ibm.team.repository.web.transport.ServiceRequest;
var ServiceResponseHandler = com.ibm.team.repository.web.transport.ServiceResponseHandler;
var TeamServerClient = com.ibm.team.repository.web.transport.TeamServerClient;

These variables should also be declared as required by the Dojo Toolkit in a .js file as Listing 8 shows.

dojo.require("com.ibm.team.repository.web.transport.ServiceRequest");
dojo.require("com.ibm.team.repository.web.transport.ServiceResponseHandler");
dojo.require("com.ibm.team.repository.web.transport.TeamServerClient");

Calling the service and requesting parameters

You might want to call a service by sending the whole input form as one of the parameters so that the service can pick up the inputs filled in the form by the user. Listing 9 is an example of how you can do that.

var service_uri = net.jazz.ajax._contextRoot+/service/
com.ibm.af.util.common.IAFFileUploadService?param1=+value1;


    var responseVar=;
    
    
    dojo.io.iframe.send({
        form: form1,
        url: service_uri,
        handleAs: "json",    
        enctype: "multipart/form-data",
        method:"post",
            
    load: function(response, ioArgs) {
            
            },

        error: function(response, ioArgs){
        
            },
        timeout: 120000  // in milli seconds	              
        });

Calling other Dojo widgets from the viewlet

If you want to call another widget or show another widget in a dialog window, use the code in Listing 10.

this._dialog = new dijit.Dialog({
                id: "detailDialog",              
                style: "height:500px;width:500px;overflow:hidden",
                                        
            
            });
        
    this._ dialog.domNode.appendChild(new Widget().domNode);

    dijit.byId('detailDialog').show();

Resources

Learn

• To learn how to create viewlets by reading the Jazz.net article about Viewlet Authoring.
  
  
• Find what you need to know about the Dojo Toolkit.
  
  
• Learn more about IBM Rational Team Concert features and benefits:
  • Rational Team Concert Information Center
  • IBM developerWorks page for Rational Team Concert, with links to many other resources
  • Webcast: Using Rational Team Concert in a globally distributed team
  • Demo: Dashboards and reports
  • Podcast: IBM Rational Team Concert and Jazz
  
  
• Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
  
  
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
  

Get products and technologies

• Rational Team Concert trial downloads (free):
  • Enterprise Edition
  • Express Edition
  • Standard Edition
  • Rational Team Concert Quick Reference
  
  
• Download these IBM product evaluation versions and get your hands on application development tools and middleware products from Rational®, DB2®, Lotus®, Tivoli®, and WebSphere®.
  
  

Discuss

• Join the discussion in Jazz.net forums.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Geetu Garg is a senior application developer for Java technology who joined IBM in 2005. She has been involved in extending and enhancing Rational Team Concert collaborative software development tools tool on the Jazz technology platform for IBM requirements.

Rate this article

Comments

Back to top

Table of contents

• Create a personal dashboard and add custom viewlets
• Alternative: Create the viewlet programmatically
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Team Concert
• Demo: Rational and Jazz
• Webcast: Agile development with IBM Rational Synergy and IBM Rational Team Concert
• Buy: Rational Team Concert

Dig deeper into Rational on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers