Customizing WebSphere Portal

You must first understand the composition of the portal page and how the page elements are aggregated before creating your custom portal site.

Make sure that you have read the Layout of the portal page section before starting any of the tasks that are described in this section.

• Creating a new theme
  Themes are a set of JSPs, images, and style sheets packaged together in a common directory structure. They can either be packaged directly in the wps.war or inside a separate WAR file of their own, or with other themes, skins, and resources.
• Importing a theme
  Perform the steps in this task to import a theme using an XML file.
• Deploying the theme
  Perform these steps to install your theme and verify that it is running.
• Using the color palette in themes
  Learn about the color palettes used in themes, define new color palettes, assign a color palette to a page, and reference a color palette in a CSS file.
• Creating a new skin
  Skins are a set of JSPs, images, and style sheets packaged as a WAR file. As deployable units, they have to follow a certain file layout which is determined by the application server and the portal server. Learn about creating your own HTML-based skins using existing skins.
• Performance guidelines for themes and skins
  After installation, IBM® WebSphere® Portal provides a default theme and skin that demonstrate the server's rich set of functions. If your site does not require all of the functionality provided by the shipped themes and skins, you can realize performance benefits by selectively removing some of those functions.
• Enabling automatic JSP reloading
  To view changes to your theme and skins JSPs without restarting the portal server, you can force the application server to automatically check for new versions of JSPs. While this is ideal for development and testing purposes, automatic JSP reloading should be disabled in a production environment because of performance issues.
• Supporting new clients
  Add a new client to your portal site using the Manage Clients administration portlets.
• Supporting new markup languages
  WebSphere Portal supports HTML markup language. You can define other markup languages to be supported, such as WML or cHTML.
• Portal style classes
  The CSS style sheets that are used for the portal page are dynamically generated by JSPs located in the /themes/Portal/ directory. You can change the tag definitions and the class definitions in the CSS style sheets. However, make sure that you do not delete any style sheets or remove any style classes. Portlets require these style classes for JSP output.
• Changing text information
  Change the text displayed in the banner of your portal page.
• Changing the page help
  Customize the help page to reflect the content and information for your organization's site.
• Working with portal navigation
  Learn how to implement navigation in a portal theme. You should be familiar with the portal structure, the Page Customizer, and the Managing Pages portlet.
• Using JSTL tags in the portal JSPs
  WebSphere Portal supports the use of tags from the JSP Standard Tag Library (JSTL).
• User and group management
  The Portal User Management Architecture (PUMA) System programming interface (SPI) provides interfaces for accessing the profiles of a portal User or Group .

Creating a new theme

Themes are a set of JSPs, images, and style sheets packaged together in a common directory structure. They can either be packaged directly in the wps.war or inside a separate WAR file of their own, or with other themes, skins, and resources.

The recommended best practice is to package them in a separate WAR file so that they are untouched across migrations and updates. This technique also enables them to be managed independently through staging operations without having to touch the wps.war application. Deploying updates to themes in separate WAR files can be done easily without having to bring the Portal server offline, particularly in clustered deployments.

If you have created themes or skins for an earlier release of WebSphere Portal , you will be able to easily migrate most of that work because the file layout and the lookup mechanisms (using the Portal custom JSP tags) to locate resources have not changed. However, the lookup works only within the same deployable unit, so resources can only be shared between themes that reside in the same WAR file.

Defining your own theme involves creating the directory structure for the artifacts of the theme. Typically, these reside in a subdirectory using a theme resource root.

The following steps describe one way of creating your own HTML-based theme using an existing theme. The steps refer to an existing theme as a sample starting point.

1. When themes are included in the wps.war, they simply need to be included in their own theme resource root under the themes/<markup> directory.
   If packaging in separate WAR : When themes are packaged in their own WAR, they need to follow the same directory structure as themes in the wps.war where the directory structure immediately following the application context root looks like this:

   /themes/<markup>/<theme_resource_root>

   For example,

   /themes/html/MyCustomTheme

   Generally, the themes directory will be a peer to the WAR's WEB-INF directory.

   To avoid problems with the directory name, do not use DBCS characters in the theme resource root directory name.

2. Copy the ar, colors, icons, images, iw, js, and status messages subdirectories from the Portal theme directory into the new theme resource root directory. These are required if the new theme will be using many of the same theme resources that the Portal theme uses, including the necessary resources for the page and portlet context menus as well as resources required by administrative portlets.

   If packaging in separate WAR : Copy the resources under themes/html/psw into the WAR's themes/html/psw directory. Also copy all the images in the /themes/html directory into the WAR's /themes/html directory as they are required for many of the administrative portlets to work in the custom theme. If the new theme needs to use the same dojo package inside the wps.war, it is best to copy the entire dojo directory from the /themes directory in wps.war into the /themes directory of the new theme's WAR.

3. Inside the theme resource root directory, create a file called Default.jsp which will be the main JSP file that the Portal server executes when rendering a Portal page using that theme. If desired, the Default.jsp and its dependent files can be copied from the Portal theme inside the wps.war as a starting point. The separate jspf files as well as the styles.jsp and its dependent .jspf files can be used in the custom theme but technically aren't required depending on the new theme's design.
   Make updates to the following files according to the requirements of your portal site.

   JSPs

   Default.jsp and its included JSPs are used to provide the appearance and layout and determine where the screen element goes. See the Themes topic for more detailed information about the JSPs (and JSPFs) that are used.

   Images

   Images are used for icons and tools within the theme pages. You can modify these images or create your own and add them to the JSPs.

   Style sheets

   In order to handle the different locales and browsers supported by a theme, the style sheets are actually JSPs. The <portal-theme:cacheProxyUrl/> tag and servlet, which is used to make sure the output of CSS JSPs is cacheable, makes sure that the JSP is aware of the current browser and locale.

   Note: For security reasons, the cache proxy servlet will only serve URLs pointing to resources located in the themes, skins, and screens directories. This makes all resources underneath these directories public. Also, any URLs containing the ".." characters will not be served.

   All style sheets reside in the css directory underneath the resource root directory of the respective theme. The main style sheet is styles.jsp , which contains only statically included JSP fragments (JSPFs - .jspf file extension). The easiest way to add your own styles is to create your own JSP fragment file and add it to styles.jsp You can change the style definitions. However, make sure that you do not delete any style sheets or remove any style classes.

4. If packaging in separate WAR : Copy all of the tld files from the WEB-INF/tld directory in wps.war into the theme WAR's WEB-INF/tld directory in order to get support for all the custom tags used for themes and skins.
5. To install the new theme in WebSphere Application Server , perform the steps described in the Deploying the theme section.
6. To make the new theme available in WebSphere Portal :
   1. Import new theme by following the steps in the Importing a theme section.
      Note: You can only make the context root of a theme known through the XML configuration interface. There is a new context-root attribute on the theme element that is used for this purpose.
   2. Edit the properties of a test page and set the page to use the new theme that you created.
      Note: Be sure to use a test page for the new theme to work out any problems before setting the default page to the new theme. Setting the portal default to use a theme with errors can cause problems accessing the portal site.
   3. When you are ready to offer the theme for general use, create a preview that users and administrators can see from the page properties.
      1. Create a screen capture of the theme.
      2. Reduce the screen capture to fit in the preview box. Recommended size is 300 x 225 pixels.
      3. Name the image preview.gif . GIF files are limited to 256 colors.
      4. Copy the image to: themes/markup_type/theme_name . In this example, the file and location is: themes/html/MyTheme/preview.gif

Note: If the Portal theme directory is either deleted or renamed, the portal resource loader uses the themes/html/Default.jsp . In this case, you should also use the fallback skin. To do this, rename the skins directory. For example, the skins/html/IBM directory should be renamed skins/html/IBM1 . If you have a broken theme, you can rename the theme and skin directories which are causing the problem to get to a working minimal theme.

Enabling Organize Favorites functionality in custom themes

The "My Favorites" feature in WebSphere Portal lets you bookmark a page in the portal so that you can return to it at a later time. The page is then added to your "My Favorites" list which is maintained by means of the Organize Favorites feature. Organize Favorites, a page containing the Organize Favorites portlet, lets you create, edit, activate, order, and delete labels and URLs in the My Favorites list.

In a default installation of WebSphere Portal Version 6.1, you cannot directly access Organize Favorites functionality. However, you can access this functionality in a newly created theme as follows:

• Use the <portal-navigation:navigation> tag with the scopeUniqueName attribute as wps.p.Favorites to create the links to the Favorites in the theme. This replaces the <portal:favoritesLoop/> tag for enabling Organize Favorites functionality.
• Create a URL to Organize Favorites in the theme using the <portal-navigation:urlGeneration> tag to wps.OrganizeFavorites .
• Create a My Favorite label as described in the topic, Enabling the Organize Favorites portlet in themes.
• Add <portal-logic:if/> tags with the pageBookmarkable attribute set to true to pages that you want to be able to bookmark.

Improving the performance of themes

WebSphere Portal includes a lightweight theme that demonstrates some of the design features that you could omit for better performance.

 

 

Importing a theme

Perform the steps in this task to import a theme using an XML file.

1. Edit DeployYourTheme.xml . Verify that the context root is correct, then save and close the file. The following is an example of how to edit this file:

   <?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 only created 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.Your_Theme" resourceroot="yourtheme" context-root="/yourtheme">
   
   <localedata locale="en">
   
   <title>Your_Theme</title>
   
   </localedata>
   
   
   <!--
   
    There's only one skin that may be combined with this theme. 
   
   -->
   
   <allowed-skin skin="NoSkin" update="set"/>
   
   </theme>
   
   </portal>
   
   </request>

2. Login to WebSphere Portal
3. Select Administration > Import XML .
4. Select the DeployYourTheme .xml file and click Import .
5. Select Administration > Themes and Skins .
6. Select the new theme and click Edit Theme .
7. Select the IBM - portal default skin and click Add > OK .
8. Select the newly added IBM skin and click Select as default .
9. Select Administration > Manage Pages > Content Root .
10. Click Home > New Page and fill out the fields for the new page using the new theme.
11. Click Home and select the new page to see the new theme applied.

Deploying the theme

Perform these steps to install your theme and verify that it is running.

1. Open the WebSphere Application Server administration console.
   1. Open a browser and enter the URL for your site.
   2. Depending on your version of WebSphere Application Server , click the appropriate option:
      • For WebSphere Application Server Version 6.1 : Click Applications > Install New Application .
      • For WebSphere Application Server Version 7.0 : Click Applications > New Application .
   3. Navigate to the yourtheme .war file.
   4. Enter your theme name as the context root. For example, /yourtheme .
   5. Click Next .
2. Change the application name from yourtheme _WAR to yourtheme and click Next .
3. Select WebSphere Portal as the installation server, then click Apply > Next .
4. Select default_host and click Next .
5. Review the summary and click Next .
6. Click Save .

To verify that the application is running:

1. Depending on your version of WebSphere Application Server , click the appropriate option:
   • For WebSphere Application Server Version 6.1 : Click Applications > Enterprise Applications .
   • For WebSphere Application Server Version 7.0 : Click Applications > Application Types > WebSphere enterprise applications .
2. Search for the new theme.
3. Select the application and click Start . A message appears that the application was started successfully.