Create a new theme


Overview

Defining custom themes involves creating the directory structure for the artifacts of the theme in a subdirectory under theme resource root.

Best practice is to package themes in a separate WAR from the wps.war application. Deploying updates to themes in separate WAR files can be done without having to bring the Portal server offline, particularly in clustered deployments.

For instructions on configuring legacy themes, see earlier portal documentation. With legacy themes lookup using custom JSP tags works only within the same deployable unit, so resources can only be shared between themes that reside in the same WAR file.

For deploying non-PageBuilder themes, see:


Example: Create theme using an existing theme

  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.

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

  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 a separate WAR, copy the resources under...

      themes/html/psw

    .into...

      WAR_FILE/themes/html/psw

    .of the WAR.

    Copy all the images in...

      /themes/html

    .to...

      WAR_FILE/themes/html

  3. Configure Dojo

    Dojo v1.4.3 The theme needs to use the Dojo package from inside the Dojo EAR application. It can address Dojo directly by using the context root of that Dojo application. Dojo is located in...

    .and can be included by using the statement...

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

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

      /portal_dojo/v1.4.3/dojo/
    Dojo v1.3.2 The theme needs to use the Dojo package from inside the Dojo EAR application. It can address Dojo directly by using the context root of that Dojo application. Dojo is located in...

    .and can be included within a JSP that inlines javascript by using the statement...

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

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

      /portal_dojo/dojo/
    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

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

  4. Inside the theme resource root directory, create a file called Default.jsp.

    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.

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

    Default.jsp and its included JSPs are used to provide the appearance and layout and determine where the screen element goes.

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

    To handle the different locales and browsers supported by a theme, the style sheets for the Portal and PortalWeb2 theme are actually JSPs. The tag and servlet <portal-theme:cacheProxyUrl/>...

    • Allows output of CSS JSPs to be cached
    • Makes sure that 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. Also, any URLs that contain double periods ( .. ) 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 own styles is to create own JSP fragment file and add it to styles.jsp You can change the style definitions. However, verify you do not delete any style sheets or remove any style classes.

    The style sheets are not JSPs in page builder. For more details refer to the section about Working with page builder.

  5. If you are packaging in a separate WAR:

    1. Copy all of the tld files from...

        WEB-INF/tld

      .in wps.war into the theme...

        WAR WEB-INF/tld

      .in order to get support for all the custom tags used for themes and skins.

    2. In the WEB-INF directory, create a file named 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>

    3. Copy the following file from the WEB-INF directory in wps.war to the corresponding directory in the theme WAR: decorations.xml.

  6. Install the new theme in WAS

  7. To make the new theme available in WebSphere Portal:

    1. Import new theme by following the steps in the Import a theme section.

      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 used for this purpose.

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

      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. c. 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

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 directory...

should be renamed...

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

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

Enable the Organize Favorites feature in custom themes

The My Favorites feature in IBM 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 My Favorites list, which is maintained by the Organize Favorites portlet. Organize Favorites lets you create, edit, activate, order, and delete labels and web addresses in the My Favorites list.


Parent

Customize the portal
Portal style classes
Work with portal navigation
Use JSTL tags in the portal JSPs
Access rights

Related tasks
Import a theme
Deploy the theme
Creat a new skin
Enable automatic JSP reloading
Add support for new clients
Add support for new markup languages
Change banner text
Work with page builder
Customize the look of the Person card

Related reference
Use the color palette in themes
Performance guidelines for themes and skins

Related information
Change the page help


+

Search Tips   |   Advanced Search