Migrate themes

 

+

Search Tips   |   Advanced Search

 

Themes developed on WebSphere Portal V5.x are compatible with WebSphere Portal V6.0 and are able to compile and render without code changes. In order for WebSphere Portal V5.x themes to function properly in WebSphere Portal Version 6.0, they should be applied to the same pages they were designed for in WebSphere Portal V5.x, using the same skins designed for use with that theme.

 

General guidelines

Use the following guidelines for migrating themes from WebSphere Portal V5.x toWebSphere Portal V6.0:

  • Migrated WebSphere Portal V5.x themes should be applied to the same pages they were designed for in WebSphere Portal V5.x.

  • WebSphere Portal V5.x themes were identified as either "administration" or "non-administration" themes. The Page Properties portlet allowed you to only assign administration themes to administration pages and non-administration themes to non-administration pages. In WebSphere Portal V6.0, themes are designed to work on all pages, so this restriction has been lifted. Themes migrated from WebSphere Portal V5.x were not coded with this in mind, so either manually enforce assigning these themes to the appropriate pages, or update the theme to support navigation across top level pages.

  • Themes should be used with the same skins used with the theme in WebSphere Portal V5.x. Some WebSphere Portal V6.0 skins take advantage of new theme functions, such as context menus, that were not available in WebSphere Portal Version 5.x themes.

The following sections provide additional information on migrating themes and skins:

 

Add support for top level page navigation

In WebSphere Portal V5.x, themes typically began rendering navigation at level 2 of the navigation model tree. Level one nodes (Home and Administration) were accessed by an URL in the themes banner that pointed explicitly to that page. With migrated themes, this method creates problems if you assign the WebSphere Portal V5.x theme to a page it was not assigned to in the WebSphere Portal Version 5.x portal environment. Say, for example, you assigned the WebSphere Portal Version 5.x Administration theme to the 'Home' page in WebSphere Portal V6.0. Since the WebSphere Portal Version 5.x Administration theme contained only a link to 'Home' in the toolbar, this theme would provide no way to navigate to Administration. Use the following guidelines to avoid this problem:

  • Add a NavigationLoop (single layer of navigation)

  • Hide unwanted pages from the navigation

    In WebSphere Portal V6.0, top level pages that you do not want to appear in the top level navigation can be hidden via a page metadata attribute. The following code excerpt is from mainMenu.jsp in the WebSphere Portal Version 6.0 IBM theme. This code must be used inside the tag <portal-navigation:NavigationLoop>

    <%
        //default to display it     boolean isNodeVisible = true; 
    
        //page metadata value used on top level nodes to hide from main menu
    
        if (wpsNavNode instanceof com.ibm.portal.MetaDataProvider) 
        {
            com.ibm.portal.MetaData iMetaData = ((com.ibm.portal.MetaDataProvider) wpsNavNode).getMetaData();               
            Object hiddenValue = iMetaData.getValue("com.ibm.portal.Hidden");
            isNodeVisible = hiddenValue == null ? true: false;
    %>
    

For more details on this code example, refer to mainMenu.jsp in the IBM theme.

 

Enable Organize Favorites functionality in themes

The "My Favorites" feature in WebSphere Portal lets you bookmark a page in the portal so that we can return to it at a later time. The page is then added to the "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.

When you migrate pre-V6.0 themes, the label necessary for Organize Favorites functionality is migrated over.

In V6.0, we can access Organize Favorites functionality via customized code by creating your own custom theme.

To enable Organize Favorites functionality in this V6.0 theme through the Administration interface, do the following:

  1. Click...

    Administration | Portal User Interface | Manage Pages | Content Root | New Label

  2. Create a label called My Favorites.

  3. Assign privileged user access to all authenticated users.

  4. Click OK when you have finished.

  5. Click...

    Portal Settings | Custom Unique Names

  6. Assign wps.My Favorites as a unique name to the My Favorites label you just created.

  7. Click OK when you have finished.

  8. Click...

    Administration | Portal User Interface | Manage Pages

  9. Add a page parameter key of "Favorites" with a value of "Yes."

Organize Favorites is considered a node under the Content Root node. Nodes are located in a level of the navigation hierarchy relative to the parent node in which they are created. The topmost node in the tree is the Content Root.

By default, users without administrative privileges can only access nodes under the Home node, which is also under the Content Root node. Users with administrative privileges can use links in the toolbar to toggle between Administration and Home. If other nodes are created directly under the Content Root, links to these nodes are not referred to unless they are specifically added to one of the theme JSPs. For more information, refer to Working with portal navigation.

 

Enable drag-and-drop functionality in migrated skins

The drag-and-drop feature lets you change the placement of individual portlets using the skins. The drag-and-drop feature lets you move a custom portlet from its current position by dropping it to another position on a page. This lets you change the arrangement of the custom portlets on a page. As this is a new feature to WebSphere Portal V6.0, we cannot directly access drag-and-drop functionality when using migrated skins. Use the following steps to enable drag-and-drop functionality in the migrated skin(s):

  1. Add the following code near the top of Control.jsp.

    <%@ taglib uri="/WEB-INF/tld/dnd.tld" prefix="dnd" %>
    <dnd:DNDPortletHelper/>
    
    <%!
    private static com.ibm.portal.identification.Identification identification;
    public void jspInit(){
        try{
            /* Perform this JNDI lookup once as it hinders performance */
            javax.naming.Context ctx = new javax.naming.InitialContext();
            identification = (com.ibm.portal.identification.Identification) ctx.lookup( "portal:service/Identification" );
        }
        catch ( javax.naming.NamingException ne ){
        // nothing is logged here because if Portal ever enters         // this catch statement then severe problems have 
            // occurred and will have already been logged by 
            // errors reported by the lookup.
     
      }
    }
    %>
    

  2. In Control.jsp, enclose the table containing the container of the portlet's "skin" with a "drag" tag. Also place a "dragHandle" tag around the portlet title bar (but not on the buttons in the title bar). The following code provides an example:

    <%-- Modification for Drag and Drop - need to pass the portlet control ID - Cannot use the tag because it is an attribute --%>
    <% 
        String currentLayoutNodeStr = "";
        if (pageContext.getAttribute("currentLayoutNode", pageContext.REQUEST_SCOPE) != null) { 
            LayoutNode currLayoutNode = (LayoutNode)pageContext.getAttribute("currentLayoutNode", pageContext.REQUEST_SCOPE);
            currentLayoutNodeStr = identification.serialize(currLayoutNode.getObjectID());
        } 
        else {
            LayoutNode currLayoutNode=(LayoutNode)pageContext.getRequest().getAttribute("com.ibm.wps.composition.element");
            currentLayoutNodeStr=identification.serialize(currLayoutNode.getObjectID());
        }
                                            
    %>
    <dnd:drag namespace="wp" type="portlet_windowID" value="<%=currentLayoutNodeStr%>" includeDragHandle="false" validator="com.ibm.wps.dnd.impl.DNDDragPortletValidator">
    
       .......   BEGIN SKIN MARKUP.......
       .......   BEGIN TITLE BAR.......
    
        <dnd:dragHandle>TITLE BAR CONTENT</dnd:dragHandle>TITLEBAR BUTTONS
    
       .......   END TITLE BAR  .......
       .......   PORTLET RENDER.......
       .......   END SKIN MARKUP.......
    </dnd:drag>
    
    

  3. Copy UnlayeredContainer-H.jsp and UnlayeredContainer-V.jsp from the WebSphere Portal V6.0 default skin into the skin's directory. If you have customized either of these files, you will want to merge the code/markup from custom versions of these files into the default skin version of these files.

 

Correcting the Search Scope drop-down list display in migrated themes

WebSphere Portal V6.0 adds a new icon to the left of the Search box in portal themes. By clicking on this icon, you are provided with a drop-down list of options for searching, including different scopes for the search, search preferences, and search help.

When migrating pre-V6.0 themes to the WebSphere Portal V6.0 installation, you may notice that this new drop-down list has a transparent background and is difficult to read. To correct this problem in migrated themes, add the following code to one of the theme's CSS files after migrating the theme. This code can be added to any CSS that is displayed with the theme.

.main-menu-item,.main-menu-item-selected {
 background-color: #FFFFFF;
}

By adding this code, the theme will have a plain white background and be easier to read. We can also customize the code to suit the color scheme of the theme.

 

WebSphere Portal V6.0 functionality in migrated themes

WebSphere Portal V6.0 adds new functionality in its theme, including portlet and people palettes and context menus. These functions are not available in a migrated WebSphere Portal V5.x theme unless the corresponding code is copied from the WebSphere Portal Version 6.0 theme. This requires you to develop a theme that identifies, copies, and tests the function you wish to add to the WebSphere Portal Version 5.x theme.

 

Known theme migration issues

WebSphere Portal V6.0 pages that are shipped with the product are assigned to use the default theme. This is done to make it easy to rebrand the WebSphere Portal by assigning a new theme to be the default theme. The exceptions are the Administration pages which are explicitly assigned the default "IBM " theme. This is done to keep the Administration pages from not working correctly if a non-functional theme is inadvertently applied to be the default theme.

This issue also occurs in migrating themes to WebSphere Portal V6.0. During migration, the default theme assignment is carried forward to the WebSphere Portal V6.0 installation. This applies the default theme from the prior WebSphere Portal release to the WebSphere Portal V6.0 pages that are shipped with the product.

If you experience problems with the pages that are shipped with the new product after migrating, assign the IBM theme to the page. If the page functions correctly with the IBM theme and not the migrated theme, there may be functional incompatibilities between the markup in the migrated theme and the content of the portlets.

It may also be that the portlets on these pages may be dependent on new functionality in WebSphere Portal V6.0 that did not exist in the prior version. If this is the case, files from the IBM theme may need to be copied into the migrated theme. Refer to the portal logs for any files that may be missing.

 

Related information

 

Parent topic:

Migrate