+

Search Tips   |   Advanced Search


Create a new theme


Overview

Themes are a set of JSPs, images, and style sheets packaged together in a common directory structure.

Themes can be packaged...

The recommended best practice is to package themes in a separate war file so that they are...

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

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


Create theme using an existing theme

  1. For themes packaged in in wps.war, create a theme resource root under...

      PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/<markup>

    For example...

      cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/html
      mkdir MyTheme

    For themes packaged in their own appname.war, follow the same directory structure as themes in wps.war, where the directory structure immediately following the application context root...

      PROFILE_HOME/installedApps/node1/wps.ear/mytheme.war/themes/<markup>/theme_resource_root

    For example:

      PROFILE_HOME/installedApps/node1/wps.ear/mytheme.war/themes/html/MyTheme

  2. Copy everything from the Portal directory into the new theme resource root directory.

      cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/html/Portal
      cp -r * ../MyTheme

    ...or you can copy selected elements...

    1. Copy the ar, colors, icons, images, iw, js, and statusmessages subdirectories from the Portal theme

      For example...

        cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/html/Portal
        cp -r ar colors icons images iw js statusmessages ../MyTheme

      If packaging in a separate WAR, copy the resources...

        cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/html
        cp -r psw PROFILE_HOME/installedApps/node1/wps.ear/mytheme.war/themes/html

    2. Copy images...

        cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/themes/html
        cp *.gif *.jpg PROFILE_HOME/installedApps/node1/wps.ear/mytheme.war/themes/html

    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 are not required depending on the new theme's design.

  3. For Dojo v1.3.2 the new theme can use the Dojo package from inside the Dojo EAR application.

    The new theme can address Dojo directly by using the application context root...

      PROFILE_HOME/installedApps/node_name/Dojo_Resources.ear/dojo.war

    ...included by using the statement...

     <c:import url="/dojo/dojo.js" 
               context="/portal_dojo" /> 
    

    ...with the value for djConfig.baseUrl set to...

      /portal_dojo/dojo/

    For Dojo v1.1.1 the theme can use Dojo by addressing it directly by the context root of the wps.war and appending the path...

      /themes/html/dojo/portal_dojo

    ...to the context root, and using the same path for the value of djConfig.baseUrl.

    Copying the Dojo bundle into the new WAR file and referencing it locally requires additional disk space and maintenance effort.

  4. Make updates to the following files according to the requirements of the portal site.

    JSPs Default.jsp and included JSPs determine appearance and screene elements.
    Images 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 Style sheets for Portal and PortalWeb2 theme are JSPs in order to handle the different locales and browsers supported by a theme.

    The <portal-theme:cacheProxyUrl/> tag and servlet, is used to ensure...

    • The output of CSS JSPs is cacheable
    • The JSP is aware of the current browser and locale

    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.

    URLs that contain double periods ( .. ) will not be served.

    All style sheets reside in...

      PROFILE_HOME/installedApps/node1/wps.ear/mytheme.war/themes/html/css

    The main style sheet is styles.jsp, which contains only statically included JSP fragments (.jspf).

    To configure styles, create your own JSP fragment file and add it to styles.jsp You can change the style definitions. Do not delete any style sheets or remove any style classes.

    The style sheets are not JSPs in page builder

  5. If packaging in a separate WAR...

    1. Copy all of the tld files from the WEB-INF/tld directory in wps.war into the theme WAR WEB-INF/tld directory in order to get support for all the custom tags used for themes and skins.

        cd PROFILE_HOME/installedApps/node1/wps.ear/wps.war/WEB-INF
        cp -r tld WP_PROFILE/installedApps/node1/wps.ear/MyTheme.war/WEB-INF/

    2. Create file...

        WP_PROFILE/installedApps/node1/wps.ear/MyTheme.war/WEB-INF/web.xml

      ...with the following content...

      <?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>
      

  6. For a theme packaged in it's own war file, deploy the theme

  7. Import new theme

    Make the context root of a theme known through xmlaccess. There is a new context-root attribute on the theme element that is used for this purpose.

  8. Edit the properties of a test page and set the page to use the new theme that you created.

    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.

  9. 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:

        PROFILE_HOME/installedApps/node1/wps.ear/MyTheme.war/themes/markup_type/theme_name

      In this example, the file and location is:

        PROFILE_HOME/installedApps/node1/wps.ear/MyTheme.war/themes/html/MyTheme/preview.gif

If the Portal theme directory is either deleted or renamed, the portal resource loader uses...

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.


Performance of themes

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


See also

Enable the Organize Favorites feature in custom themes
Customize the portal
Portal style classes
Work with portal navigation
Use JSTL tags in the portal JSPs
User and group management
Import a theme
Deploy the theme
Creating a new skin
Enable automatic JSP reloading
Supporting new clients
Supporting new markup languages
Changing banner text
Work with page builder
Customize the look of the Person menu
Use the color palette in themes
Performance guidelines for themes and skins
Changing the page help