Deploying a theme WAR file to IBM WebSphere Portal V6.1

This article is designed to show portal administrators how to create and deploy a theme WAR file in an IBM® WebSphere® Portal V6.1 environment. Included is a sample theme WAR file.

Share:

Loc Dang (locdang@us.ibm.com), IT Specialist, IBM

Loc Dang is an IT Specialist working with IBM Software Services for Lotus. He is a member of the Portal Practice within ISSL and has more than 9 years' experience working with WebSphere Application Server and WebSphere Portal. You can reach him at locdang@us.ibm.com.



Michael Fitzgerald (maf@us.ibm.com), IT Specialist, IBM

Mike Fitzgerald is an IT Specialist working with IBM Software Services for Lotus. He is a member of the Portal Practice within ISSL and has more than 6 years ' experience working with various flavors of WebSphere Portal. You can reach him at maf@us.ibm.com.



28 June 2010

Also available in Chinese

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

With the advent of WebSphere Portal V6.1, many administrative features changed. One key change involves how themes and skins are handled. No longer are they file system artifacts. They can now be exported and imported as WAR files. This ability makes the task of administering themes and skins, and migrating between versions, different. Portal administrators now must be familiar with creating WAR files. This article takes a step-by-step approach to help the experienced administrator understand how to make use of this new feature.

You should meet the following prerequisites to use this new feature:

  • Understanding of the IBM WebSphere Application Server and WebSphere Portal V6.1 directory structure
  • Understanding of the basic functions of the WebSphere Portal administrative console
  • Understanding of the basic operating systems commands

This articles includes two sample files, available in the Downloads section:

  • sample_DeployYourTheme.xml is a sample file used to import and create the theme in WebSphere Portal V6.1. Refer to the “Importing the theme” section for a better understanding of how to import the theme.
  • MyTheme.war is a sample theme for WebSphere Portal V6.1. Refer to the “Creating a theme WAR file” section for a better understanding of how to create the WAR file.

Creating a theme WAR file

The first step in being able to deploy a theme WAR file is to create one. This creation is a simple process. One method is to create a directory and name it /home/MyTheme. Next, copy an existing theme to it. Here is a useful UNIX® command that does this task:

cd <wps.ear>/wps.war/themes/html/Portal
tar cf . - | (cd /home/MyTheme; tar xvfBp -)

This command recursively goes through the /html/Portal subdirectory and copies everything there into /home/MyTheme.

Now you can make changes that identify your personalized theme. If you want to have a look and feel to your custom theme that is more like web 2.0, then change the source destination from /Portal to /Portal2.

You can now skip to step 14 in the following list of steps.

If you want to create your theme from scratch, you can follow these steps:

  1. Create a directory called MyTheme.
  2. Under the MyTheme directory, create two other directories, themes and WEB-INF:

    MyTheme/themes
    MyTheme/WEB-INF
  3. Copy the WebSphere Portal dojo directory and its content from the original theme location, and paste it to the MyTheme/theme directory:

    cp –r <wps.ear>/wps.war/themes/dojo MyTheme/themes/
    MyTheme/themes/dojo/*
  4. Create an HTML directory under the themes directory:

    MyTheme/themes/html
  5. Copy the original WebSphere Portal theme’s psw directory to the HTML directory:

    cp –r <wps.ear>/wps.war/themes/html/psw MyTheme/themes/html/
    MyTheme/themes/html/psw
  6. Create the MyTheme directory under HTML:

    MyTheme/themes/html/MyTheme
  7. Insert your new theme in the newly created MyTheme directory.

    NOTES:

    • If you don’t have a theme at the moment, copy the original WebSphere Portal theme to the newly created MyTheme directory:

      cp –r <wps.ear>/wps.war/themes/html/Portal/* MyTheme/theme/html/MyTheme
    • It is best to start from the original WebSphere Portal theme and modify it.
  8. Under the MyTheme/WEB-INF directory, create the file web.xml: MyTheme/WEB-INF/web.xml
  9. web.xml must contain the information shown in listing 1.

    Listing 1. Sample web.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://java.sun.com/xml/ns/j2ee"				    
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    id="MyTheme"
    version="2.4"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
    http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
    <display-name>MyTheme</display-name>
    </web-app>

    NOTE: If this code was copied from the WebSphere Portal Information Center, verify that you have deleted all the spaces at the beginning of each line. If the spaces have not been deleted, the WebSphere Application Server determines that errors exist in the web.xml file when the WAR file is installed.

  10. Update the web.xml file by replacing the MyTheme variable with the name of your theme.
  11. Create the tld directory under the WEB-INF directory:

    MyTheme/WEB-INF/tld
  12. Copy all the tld files from the original wps.war file into the newly created tld directory:

    cp –r <wps.ear>/wps.war/WEB-INF/tld* MyTheme/WEB-INF/tld

    MyTheme/WEB-INF/tld/portal-v6-core.tld
    MyTheme/WEB-INF/tld/portal-v6-dynamicui.tld
    MyTheme/WEB-INF/tld/portal-v6-fmt.tld
    MyTheme/WEB-INF/tld/portal-v6-logic.tld
    MyTheme/WEB-INF/tld/portal-v6-navigation.tld
    MyTheme/WEB-INF/tld/portal-v6-showtools.tld
    MyTheme/WEB-INF/tld/portal-v6-skin.tld
    MyTheme/WEB-INF/tld/portal-v6-theme-ext.tld
    MyTheme/WEB-INF/tld/portal-v601-web20.tld
  13. Place your custom tld files in the MyTheme/WEB-INF/tld directory.
  14. Compress the MyTheme’s content into a ZIP file called MyTheme.zip, containing the following files:

    themes/html/MyTheme/*
    themes/html/psw/*
    themes/dojo/*
    WEB-INF/web.xml
    WEB-INF/tld/*
  15. Rename MyTheme.zip as MyTheme.war.

Deploying the theme on WebSphere Portal V6.1

The next step is to deploy the theme WAR file to the portal server. You can accomplish this task by following these steps:

  1. Open a browser, and set the URL to the WebSphere Application Server administrative console:

    http://<hostname>:<port>/admin For example:

    http://MyHostName.raleigh.ibm.com:10027/admin
  2. Select Applications - Install New Application as shown in figure 1.

    Figure 1. Left navigation panel of the WebSphere Application Server console
    Left navigation panel of the WebSphere Application Server console
  3. In the “Preparing for the application installation” window that displays, select Local file system, click Browse, and browse to MyTheme.war. In the Context root field enter /MyTheme. Click Next. See figure 2.

    Figure 2. Preparing for the application installation
    Preparing for the application installation
  4. In the Install New Application window that displays, select Step 1: Select installation options, and remove the “_war” from the application name in the Application Name field. The default name given is the first portion of the WAR file name with “_war” added to it. Click Next. See figure 3.

    Figure 3. Select installation options
    \Select installation options
  5. In the Install New Application window that displays, select Step 2: Map modules to servers, select the WebSphere Portal server and the portal cluster (if there is a cluster) in the Clusters and Servers field, and select the MyTheme module. Click Apply, and then click Next. See figure 4.

    Figure 4. Map modules to servers
    Map modules to servers
  6. Select Step 3: Map virtual hosts for web modules, select the web module MyTheme, and in the Virtual host field select default_host. Click Next. See figure 5.

    Figure 5. Mapping virtual hosts for Web modules
    Mapping virtual hosts for Web modules
  7. In the window that displays Step 4: Summary, verify that all the information that is shown in the summary of installation options is correct. Click Finish. See figure 6.

    Figure 6. Summary
    Summary
  8. In the window that displays the installation messages, as shown in figure 7, click the Save link to save these selections to the master configuration. You are returned to the main WebSphere Application Server administrative console.

    Figure 7. Installation messages
    Installation messages
  9. In the administrative console, select Applications - Enterprise Applications to open the window titled Enterprise Applications, as depicted in figure 8.

    Figure 8. Left navigation panel of the WebSphere Application Server administrative console
    Left navigation panel of the WebSphere Application Server administrative console
  10. In the Enterprise Applications window shown in figure 9, select the box next to the application MyTheme. Click Start.

    Figure 9. Enterprise Applications
    Enterprise Applications

Importing the theme

Importing your theme into the WebSphere Portal server involves several steps. One method for easing this process is to make use of an XML file. We will demonstrate this approach below. The first step is to create an XML file. We have included the sample code, which you can use as a reference, in listing 2.

  1. Create a file called DeployYourTheme.xml.
  2. Enter the code shown in listing 2.
    Listing 2. Sample XML file for deploying a theme
    <?xml version="1.0" encoding="UTF-8"?>
    <request 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="PortalConfig_6.1.0.xsd"
    type="update" create-oids="true">
    
    <portal action="locate">
    <!--
    Sample for deploying themes and skins in an XML script. Note that this 
    created only the database entries;
    you still need to provide the rendering JSPs under the resource root 
    directories specified in the XML. 
    -->
    <skin action="update" active="true" objectid="NoSkin" 
    uniquename="wps.skin.noSkin" resourceroot="NoSkin" >
    <localedata locale="en">
    <title>NoSkin</title>
    <description>A skin with no skin</description>
    </localedata>
    </skin>
    
    <theme action="update" active="true" defaultskinref="NoSkin" 
    uniquename="ibm.portal.theme.MyTheme" 
    resourceroot="MyTheme" 
    context-root="/MyTheme">
    <localedata locale="en">
    <title>MyTheme</title>
    </localedata>
    
    <!--
     There's only one skin that can  be combined with this theme. 
    -->
    <allowed-skin skin="NoSkin" update="set"/>
    </theme>
    </portal>
    </request>
  3. Modify the DeployYourTheme.xml file by changing anything that is MyTheme with the name of your theme to make it consistent with the rest of this document.
  4. Open a browser and set the URL to WebSphere Portal:

    http://<hostname>:<port>/wps/portal For example:

    http://MyHostName.example.com:10040/wps/portal
  5. Log in to the WebSphere Portal site with an administrative ID as shown in figure 10.

    Figure 10. WebSphere Portal Login screen
    WebSphere Portal Login screen
  6. Select the Administration tab on the banner menu as shown in figure 11.

    Figure 11. WebSphere Portal Welcome page
    WebSphere Portal Welcome page
  7. Select Portal Settings - Import XML as shown in figure 12.

    Figure 12. WebSphere Portal Administration tab
    WebSphere Portal Administration tab
  8. Click Browse, and locate the file DeployYourTheme.xml.
  9. Click Import.
  10. Select Portal User Interface - Themes and Skins, as shown in figure 13.

    Figure 13. WebSphere Portal Themes and Skins administration page
    WebSphere Portal Themes and Skins administration page
  11. In the Themes section, select MyTheme and click the Edit theme button.
  12. In the All skins section of the window that displays , select IBM – portal default. See figure 14.

    Figure 14. Themes and Skins edit page
    Themes and Skins edit page
  13. Click to move the IBM skin over to the right section of the window, the section titled Skins for this theme.
  14. Select IBM in the right selection box.
  15. Select Set as default, and click OK when prompted.

You have completed the process of creating a new theme, converting it to a WAR file, importing the WAR file into the WebSphere Application Server, and starting the Enterprise Application (the WAR file). After the Enterprise Application (the WAR file) was started, you were able to import the theme into WebSphere Portal using the XML file, and you enabled WebSphere Portal to use the newly added theme. The next steps take you through the process of testing the theme in WebSphere Portal.


Testing the new theme

The easiest step is to test your new theme.

  1. Log in to the WebSphere Portal site with an administrative ID, as shown in figure10.
  2. Select the Administration tab on the banner, as shown in figure 11.
  3. Select Portal User Interface - Manage Pages, as shown in figure 15.

    Figure 15. WebSphere Portal Administration Manage Pages window
    WebSphere Portal Administration Manage Pages window
  4. In the window that displays, select Content Root.
  5. In the window that displays, click New Page, as shown in figure 16.

    Figure 16. Manage Pages window after Content Root has been selected
    Manage Pages window after Content Root has been selected
  6. In the Page Properties, shown in figure 17, do the following:
    • In the Title field, enter NewPage.
    • In the Theme field, select MyTheme from the pull-down menu.
    Figure 17. Page Properties window for a newly created page
    Page Properties window for a newly created page
  7. Click OK. After the page has been created, you are returned to the Manage Pages page of the Administrative tab. See figure 18.

    Figure 18. WebSphere Portal Administrative tab – Manage Pages
    WebSphere Portal Administrative tab – Manage Pages
  8. Select More on the banner menu.
  9. You see the Page Menu for NewPage, as shown in figure 19. Select New Page.

    Figure 19. WebSphere Portal page display after More has been selected
    WebSphere Portal page display after More has been selected

Figure 20 displays the new page (NewPage) that you just created, utilizing the new theme (MyTheme).

Figure 20. WebSphere Portal displaying the NewPage window
WebSphere Portal displaying the NewPage window

Conclusion

In this article, we have gone through the steps necessary to create, deploy, install, and use a theme, as a WAR file, in WebSphere Portal V6.1. In the references sited below, we have included a link to the section within the WebSphere Portal Server Information Center that discusses performance guidelines for themes and skins. This section is a “must read” for those individuals creating or designing themes and skins.


Acknowledgments

We extend our thanks to Shannon Pixley for her help with the web.xml file and to Morgan Johnson for the theme sample.


Downloads

DescriptionNameSize
Code samplesample_DeployYourTheme.xml1KB
Code sampleMytheme.war11.3MB

Resources

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=497656
ArticleTitle=Deploying a theme WAR file to IBM WebSphere Portal V6.1
publish-date=06282010