Deploying a theme WAR file to IBM WebSphere Portal V6.1
Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.
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:
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:
- Create a directory called MyTheme.
- Under the MyTheme directory, create two other directories, themes and WEB-INF:
- 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/
- Create an HTML directory under the themes directory:
- 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/
- Create the MyTheme directory under HTML:
- Insert your new theme in the newly created MyTheme directory.
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.
- If you don’t have a theme at the moment, copy the original WebSphere Portal theme to the newly created MyTheme directory:
- Under the MyTheme/WEB-INF directory, create the file web.xml:
- 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.
- Update the web.xml file by replacing the MyTheme variable with the name of your theme.
- Create the tld directory under the WEB-INF directory:
- 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
- Place your custom tld files in the MyTheme/WEB-INF/tld directory.
- Compress the MyTheme’s content into a ZIP file called MyTheme.zip, containing the following files:
- 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:
- Open a browser, and set the URL to the WebSphere Application Server administrative console:
- Select Applications - Install New Application as shown in figure 1.
Figure 1. Left navigation panel of the WebSphere Application Server console
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- In the Enterprise Applications window shown in figure 9, select the box next to the application MyTheme. Click Start.
Figure 9. 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.
- Create a file called DeployYourTheme.xml.
- 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." resourceroot="" context-root="/"> <localedata locale="en"> <title></title> </localedata> <!-- There's only one skin that can be combined with this theme. --> <allowed-skin skin="NoSkin" update="set"/> </theme> </portal> </request>
- 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.
- Open a browser and set the URL to WebSphere Portal:
- Log in to the WebSphere Portal site with an administrative ID as shown in figure 10.
Figure 10. WebSphere Portal Login screen
- Select the Administration tab on the banner menu as shown in figure 11.
Figure 11. WebSphere Portal Welcome page
- Select Portal Settings - Import XML as shown in figure 12.
Figure 12. WebSphere Portal Administration tab
- Click Browse, and locate the file DeployYourTheme.xml.
- Click Import.
- Select Portal User Interface - Themes and Skins, as shown in figure 13.
Figure 13. WebSphere Portal Themes and Skins administration page
- In the Themes section, select MyTheme and click the Edit theme button.
- In the All skins section of the window that displays , select IBM – portal default. See figure 14.
Figure 14. Themes and Skins edit page
- Click to move the IBM skin over to the right section of the window, the section titled Skins for this theme.
- Select IBM in the right selection box.
- 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.
- Log in to the WebSphere Portal site with an administrative ID, as shown in figure10.
- Select the Administration tab on the banner, as shown in figure 11.
- Select Portal User Interface - Manage Pages, as shown in figure 15.
Figure 15. WebSphere Portal Administration Manage Pages window
- In the window that displays, select Content Root.
- In the window that displays, click New Page, as shown in figure 16.
Figure 16. Manage Pages window after Content Root has been selected
- 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
- 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
- Select More on the banner menu.
- 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
Figure 20 displays the new page (NewPage) that you just created, utilizing the new theme (MyTheme).
Figure 20. WebSphere Portal displaying the NewPage window
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.
We extend our thanks to Shannon Pixley for her help with the web.xml file and to Morgan Johnson for the theme sample.
- Read the article, "Creating a new theme," in the WebSphere Portal V6.1 Information Center.
- Read the article, "Importing a theme," in the WebSphere Portal V6.1 Information Center.
- Read the article, "Deploying the theme," in the WebSphere Portal V6.1 Information Center.
- Read the article, "Performance guidelines for themes and skins," in the WebSphere Portal V6.1 Information Center.
- Refer to the Web Portal software from WebSphere product page on developerWorks®.