Develop and deploy new themes and skins for IBM Mashup Center

This article introduces the theme and skin model in IBM® Mashup Center. It guides you to develop a customTheme theme and a ThinTitle skin, and it shows you how to deploy the theme WAR file in a production environment.

Qian Jie (Jove) Zhong, Software Developer, IBM

Jove Zhong is the team leader of the IBM Lotus Mashups UI development team in Shanghai. He's been working for IBM for four years, mainly focusing on Flash- or AJAX-based rich Internet application development.



Zheng (Erik) Bi, Software Developer, IBM

Zheng Bi (Erik) is a Software Engineer on the IBM Lotus Mashups UI development team at the China lab, specializing in Java and Web technology. He has been involved in Web application development for more than two years. You can reach him at bizheng@cn.ibm.com.



Wei (Marshall) Shi, Software Developer, IBM

Wei Shi (Marshall) is a Software Engineer on the IBM Lotus Mashups UI development team at China Lab. He is interested in Web 2.0 technology and has been working on related projects for more than two years. You can reach him at shiwcsdl@cn.ibm.com.



Peng Yu (Joard) Zhang, Software Developer, IBM

Peng Yu (Joard) Zhang is a Software Engineer on the IBM Lotus Mashups UI development team at the China lab.



21 October 2008

Also available in Japanese

IBM Mashup Center, as the industry's integrated enterprise Web 2.0 mashup software, is a complete end-to-end mashup platform. It supports line-of-business assembly of simple, flexible, and dynamic Web applications, with the management, security, and governance capabilities that IT requires. In Mashup Center, IBM has created a lightweight widget model and defined a standard for widgets. As part of this effort, IBM is leading a new widget specification workgroup in OpenAJAX.

Core UI components in Lotus Mashups

IBM Mashup Center integrates Lotus Mashups and InfoSphereâ„¢ MashupHub. The introduction of the product as a whole is beyond the scope of this article. In this article, we introduce the main user interface (UI) components for Lotus Mashups. You should have a background knowledge of core UI components to develop a new theme and skin.

A theme is a plain HTML file that organizes all the system-level widgets, such as navigation, banner, palette, and layout. Figure 1 shows an overview of the structure of a mashup page.

Figure 1. Overall UI structure of a mashup page
Overall UI structure of a mashup page

Everything in the theme is an iWidget

Everything in the theme is an iWidget. iWidgets are defined in simple HTML fragments. For example, the HTML fragment of the navigation iWidget is shown in listing 1.

Listing 1. Navigation iWidget
<div class="mm_iWidget" id="navigator"> 
<a class="mm_Definition" href="/mum/widget-catalog/navigator.xml"></a> 
</div>

System widgets

System widgets are core to IBM Lotus Mashups. You cannot add them into a mashup page on the fly. They are mainly used to present the main UI of Lotus Mashups, including the page navigation, palette, banner, and page layout. Here are brief introductions of some system widgets:

  • Navigation. You can use the Navigation widget to switch pages and to create, delete, and share pages.
  • Mode selector. You can use the mode selector widget to switch page modes between View and Edit. Through the mode selector, you can also go to the InfoSphere MashupHub main page or view pages shared by other users.
  • Banner. Use the banner widget to display the page title. It also serves as the host of the mode selector widget, the open search widget, and the system message widget.
  • Palette. Use the palette widget to organize all available production widgets in each of several widget categories. You can drag a widget from the palette and drop it into the mashup page canvas.
  • HTML content. The HTML content widget holds the real content of the mashup page. The mashup page is based on either a freeform or column layout.

Production widgets

Production widgets are those functional widgets in the palette category. You can add them into their mashup page on the fly for the specific usage. For example, you can add a FeedViewer widget to your mashup page to read feeds using a feed URL. You also can add a DataViewer widget to the mashup page to display data from a data source in a table.


Theme and skin programming model

Themes and skins provide the look and feel of IBM Lotus Mashups. A theme specifies all the system-level widgets, the whole page look, and the artifacts used in the current page. Lotus Mashups enables you to add a new theme in a production environment.

A skin is the decoration that displays around the content of a widget. Each skin is an HTML template. You can create any kind of skin, which is based on a simplified template skeleton, that you like. A skin is an element that belongs to a specific theme. One theme can have different skins.

IBM Lotus Mashups delivers one default theme and four default skins.

Theme and skin models

The theme and skin as a whole can be created in a WAR file. When you deploy the theme WAR file on a WebSphere® Application Server that has IBM Lotus Mashups installed, the newly deployed theme can be detected and loaded by Lotus Mashups.

A typical theme WAR file contains the definition of all the system widgets such as the navigation, palette, and banner widgets. It also needs to list all the skins of the theme. Each skin in the theme is loaded by a skin service in Lotus Mashups. When you wrap all of the skin HTML template files, CSS files, and other resource files in a separate file folder and then add this folder into the theme WAR file, the skin can be loaded automatically by the skin service.

When a widget is dragged from the palette and dropped into a page, the default skin type of the current page layout is applied to the widget. You can check or change the default skin in the configuration window of the current page layout widget.


Build a new theme and skin step by step

You can develop your customized theme and skin using your favorite text editor or the Eclipse IDE. Some popular Eclipse plug-ins such as Aptana can also help. In this step-by-step section, we use Eclipse IDE without additional plug-ins.

Organize the theme and skin directory

The folders that contain the theme and skin source code should be organized as shown in figure 2.

Figure 2. Customized theme folder organization
Customized theme folder organization

The name of the themes folder is arbitrary; you can use resources, mythemes, and so on. The folder name should be specified in the mashups.properties file:

themeRootDir=themes

A customized theme is created in this theme folder. In this article, we create a new theme named customTheme with a new skin called ThinTitle.

Figure 3. New theme and skin
New theme and skin

Create a new theme

In this section, we create a new theme that looks like the one shown in figure 4. We include some system widgets in the theme, and customize other optional resources such as background color and logo image. We create this new theme following these steps:

  1. Define the new theme metadata in the metadata.xml file.
  2. Write the theme UI code in the theme.html and theme.css files.
Figure 4. Look of the new theme
Look of the new theme

metadata.xml

The metadata contains the internationalized names of the theme, a numeric ID to identify it, and the theme’s default skin name. See listing 2.

Listing 2. metadata.xml
<metadata> 
       <title> 
              <nls-string language="en">Custom Theme</nls-string> 
              <nls-string language="zh">自定义主题</nls-string> 
       </title> 
       <id>3</id> 
       <default-skin>Glass</default-skin> 
</metadata>

theme.html and theme.css

You use theme.html to address the layout of the system widgets. The styles used in theme.html file are defined in theme.css. The new theme that you create is slightly different from the default one, and the system widgets are like the one shown in figure 5.

Figure 5. New theme layout
New theme layout

Theme.html, shown in listing 3, organizes all the system widgets in a plain <div> element. The styles attached to these div elements are defined in theme.css.

Listing 3. theme.html
<div class="customTheme_main" align="center">       
    <div class="customTheme_top" align="left"> 
      <!-- Common Actions --> 
        <div class="customTheme_action">
        <div class="mm_iWidget" id="commonAction"> 
        <a class="mm_Definition" 
href="/mum/widget-catalog/commonActions.xml"></a> 
          </div> 
          </div>            
     <!-- Navigator --> 
        <div class="customTheme_navigator"> 
            <div class="mm_iWidget" id="navigator"> 
                <a class="mm_Definition" 
                href="/mum/widget-catalog/navigator.xml"></a> 
                </div> 
              </div>            
       </div>     
       <div class="customTheme_content" align="left"> 
        <!-- Banner -->             
              <div class="mm_iWidget" id="banner"> 
                     <a class="mm_Definition" 
                     href="/mum/widget-catalog/banner.xml"></a> 
              </div> 
        <!-- Palette -->              
              <div class="mm_iWidget" id="palette"> 
                     <a class="mm_Definition" 
                     href="/mum/widget-catalog/palette.xml"></a> 
              </div>            
        <!-- Html Content --> 
              <div class="mm_iWidget" id="htmlContent" style="height:100%;"> 
                     <a class="mm_Definition" 
                     href="/mum/widget-catalog/htmlContent.xml"></a> 
                     <span class="mm_ItemSet" title="attributes"> 
                            <a class="mm_Item" 
                            href="#url">%mm.selectpageurl%</a> 
                     </span>                 
              </div>            
       </div> 
</div>

Create a new skin

Every theme can have multiple skins. You can create a ThinTitle skin under the customized theme; the skin has a light blue title and a thin border, as shown in figure 6.

A skin wraps the widget. A skin has a title bar to host the widget icon, the widget title, the wiring icon, and the configuration icon. The title bar serves as a drag handler that lets you drag the widget. The title bar is not part of ThinTitle, but instead is part of the Lotus Mashups skin service. The skin service creates this title bar for every skin. The widget body area displays the widget content. The resize bar at the bottom lets you change the width and height of the widget.

Figure 6. ThinTitle skin
ThinTitle skin

Follow these steps to create the ThinTitle skin:

  1. Define the new skin metadata in the skin’s metadata.xml file. See listing 4.
  2. Create the skin UI in the skin.html (see listing 5) and skin.css files.
  3. Define the JavaScriptâ„¢ object for this new skin in the skin.js file.
  4. Create other optional resources such as images in the skin folder.
Listing 4. metadata.xml
<metadata> 
<title> 
    <nls-string language="en">ThinTitle</nls-string> 
    <nls-string language="zh">瘦标题</nls-string> 
</title> 
<id>ThinTitle</id> 
<preview-url>preview.jpg</preview-url> 
</metadata>

The skin metadata contains its internationalized name, ID, and preview picture information.

Listing 5. skin.html
<div style="${location}" class="ThinTitle_main" id="${skinId}"> 
       <div id="${widgetBodyId}" class="widgetBody"> 
              <div class="ThinTitle_text"> 
                     <img src="${iconUrl}" class="ThinTitle_icon"/>${title} 
              </div>     
              <div id="${widgetContentId}">    
                     <div style="height:24px;"></div>  
                     ${widgetBody} 
              </div>     
            <div id="${resizerId}" class="ThinTitle_drag"></div> 
       </div>  
</div>

The entire skin must contain the widget body area and the widget content area. We also use the title and the resize handler for our ThinTitle skin. The layout of the skin is shown in figure 7.

Figure 7. Skin layout
Skin layout

Some placeholders (${variable}) in skin.html are populated during runtime with their actual values in the skin.js file, shown in listing 6. The skin service leverages these variables to draw out the skin and the widget inside it. The mandatory variables are these:

  • ${location}. The position of the widget, which must be specified in the outmost <div>.
  • ${skinId}. The skin’s ID.
  • ${widgetBodyId}. The widget wrapper’s ID. Note that you also need to specify class="widgetBody" for this wrapper DIV.
  • ${widgetContentId}. The widget content area’s ID.
  • ${widgetBody}. The real widget content.

Other useful values are these:

  • ${iconUrl}. The widget icon URL.
  • ${title}. The widget title.
  • ${resizerId}. The resize handler’s ID.
Listing 6. skin.js
{ 
       widgetId:"", 
       location:"", 
       title:"", 
       widgetContentId:"", 
       widgetBodyId:"", 
       iconUrl:"", 
       resizerId:"", 
       
//TODO: add your customized variable here 
  
       process:function(skinId, tagId) { 
              var domNode=dojo.byId(tagId); 
              this.location = domNode.getAttribute("locationstyle"); 
  
              this.resizerId = tagId + "_resizer"; 
              this.widgetContentId = tagId + "_content"; 
              this.widgetId = tagId; 
              this.widgetBodyId = tagId + "_widgetBody"; 
              
        // get the icon url 
              var widgetObj = mainPage.getWidgetMetadataByInstanceId(domNode);    
              if (widgetObj!=null){ 
                     this.iconUrl = widgetObj.widgetIconSrc; 
              } 
  
        // TODO: Add your customized code here 
       } 
}

The value of those variables defined in the skin.html file are set using process(skinId, tagId). The process function is called when the skin is rendered, so any special code can be added here to make a customized skin.

You can use some optional variables in the skin.js file:

  • minHeight. The minimal height of the skin wrapper when you resize it.
  • minWidth. The minimal width of the skin wrapper when you resize it.
  • marginHeight. The top margin between the widget body and the skin wrapper.
  • marginWidth. The bottom margin between the widget body and the skin wrapper.
  • resizerHeight. The height of the resize handler.

Package and deploy

You can use the Eclipse IDE to export the project to a WAR file, or you can compress the project and rename it *.war. In this case, we assume that you package the project in a file called myTheme.war. Then in the WebSphere Application Server console, you can install this WAR file with a not-used context root, then use other default settings to deploy it. After you deploy the WAR file, start it to take effect. See figure 8.

Figure 8. Deploy the WAR file on WebSphere Application Server
Deploy the WAR file on WebSphere Application Server

To test your new theme and skin, log in to Lotus Mashups, open a mashup page, and change its theme to Custom Theme as shown in figure 9. Then you can place some widgets on the canvas and change their skin to ThinTitle as shown in figure 10.

Figure 9. Change the page theme to Custom Theme
Change the page theme to Custom Theme
Figure 10. Change the skin to ThinTitle skin
Change the skin to ThinTitle skin

Limitations

In Lotus Mashups 1.0, you face some limitations when developing a new theme and skin.

Theme limitations

The theme should contain at least a theme.html file and a theme.css file under a file folder named as the theme name. The theme.html file must have all core widgets including navigation, palette, banner, HTML content, and common action widgets. If you delete any one of them, unpredictable exceptions occur during runtime. The style information should be contained in the theme.css file. Other CSS files in this folder are not supported yet.

Skin limitations

There are several limitations to skins:

  • A skin named glass should be set as the default skin in a new theme.
  • The skin.html template file has these reserved variables as placeholders, skinId and widgetBody:
    • skinId represents the unique ID in the HTML DOM tree after the skin is applied in the widget.
    • widgetBody represents the area that displays the widget content.
  • The skin preview image must be named preview.jpg in the skin directory.
  • To make the skin resizeable, specify another placeholder, called resizerId, in the skin.html file.

Conclusion

IBM Lotus Mashups provides a lightweight theme and skin framework. Users and developers can replace the current theme and skin with their own customized theme and skin.


Download

DescriptionNameSize
Code samplecustomTheme.war40.2KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Sample IT projects
ArticleID=346438
ArticleTitle=Develop and deploy new themes and skins for IBM Mashup Center
publish-date=10212008