Create a new theme

 

+

Search Tips   |   Advanced Search

 

Themes 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 jointly determined by the application server and the portal server.

If you have created themes or skins for an earlier release of WebSphere Portal you will be able to migrate most of that work because the file layout and the lookup mechanisms to locate resources have not changed. However, the lookup only works 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 the theme name, although technically that is not necessary as long as this WAR file will only contain one and only one theme.

Themes are located under...

was_profile_root/installedApps/cell/wps.ear/wps.war/themes

Deploying custom themes to wps.war involves creating theme resources and then war'ing them up. In MyTheme.war, for example, you would have the following directories

/themes
/themes/dojo
/themes/html
/themes/html/MyTheme
/WEB-INF

You can add your new MyTheme theme directory right under...

...and then go to...

Administration | Themes and Skins | Add New Theme

...and it should work right away.

If a new wps.ear is deployed, your theme would get wiped out. Build and install the war file to add the theme permanently. Copies of the standard theme might require a fix to work. Check with IBM support.

If you install the MyTheme.war to the cluster it will be pushed to all nodes.

 

Package and deploy your custom theme

Themes can either be...

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 without having to bring the Portal server offline.

The following steps describe one way of creating your own HTML-based theme using an existing theme...

  1. For themes included in wps.war, create...

      themes/<markup>/mytheme

    Do not use DBCS characters in the theme resource root directory name.

    If packaging as part of wps.war:

    Create a directory structure similar to existing themes directory structure. For example...

      cd wp_profile/installedApps/F32BC/wps.ear/wps.war
      cp -r themes /workarea/mythemes

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

  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.

    Copy the resources under...

      themes/html/psw

    ...into the WAR's directory...

      themes/html/psw

    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.

      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.

    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.

    If you have problems with places where "portal-logic:urlFindInTheme" tag is used, try using this tld file, portal-v6-logic.zip, and restart your Theme war.

  4. To install the new theme in WebSphere Application Server, perform the steps described in the Deploying the theme section.

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

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

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

    • When you are ready to offer the theme for general use, create a preview that users and administrators can see from the page properties.

      • Create a screen capture of the theme.

      • Reduce the screen capture to fit in the preview box. Recommended size is 300 x 225 pixels.

      • Name the image preview.gif. GIF files are limited to 256 colors.

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

 

Create your own HTML-based theme using an existing theme

  1. Create a new directory path...

    themes/html/MyTheme

    To avoid problems with the directory name, do not use DBCS characters.

  2. Copy all of the files and subdirectories from another theme directory into the new. For example...

      WP_PROFILE/installedApps/CELL/wps.war/themes/html/Portal

    If you use the Portal theme, also copy the resources under...

    WP_PROFILE/installedApps/CELL/wps.war/themes/html/psw

    ...which are required by this theme.

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

    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 tag and servlet...

    <portal-theme:cacheProxyUrl/>

    ...is used to make sure the output of CSS JSPs is cacheable and 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 in themes, skins, and screens directories. This makes all resources underneath these directories public.

    Any URLs containing the ".." characters will not be served.

    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 (*.jspf).

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

  4. Next to the "themes" directory, create a WEB-INF.

  5. In this 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>

  6. Copy the dojo directory from the wps.war file beneath the "themes" directory.

  7. Create the subdirectory WEB-INF/tld.

  8. Copy all tld files to the WEB-INF/tld.

  9. Wrap the new theme as MyTheme.war using a ZIP compression tool.

      jar cvf MyTheme.war MyTheme

  10. To install the new theme in WAS:

    1. Open the application server admin console.

    2. Select...

      Applications | Install New Application | Install

      ...and proceed through the wizard to deploy the WAR file that you have just created.

      Note the context root that the WAR file is deployed under because it will be required later.

    3. Verify the newly deployed web application is started.

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

    1. Use the Themes and Skins portlet under...

      Administration | Portal User Interface

      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.

      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

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

themes/html/Default.jsp

In this case, you should also use the fallback skin. To do this, rename the skins.

For example, the directory...

skins/html/IBM

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

 

Enable 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 v6, you cannot directly access Organize Favorites functionality. The following tasks, however, can be done to access Organize Favorites functionality in your newly created theme by doing the following:

  1. Use the tag...

    <portal-navigation:navigation>

    ...with the scopeUniqueName attribute as wps.p.Favorites to create the links to the Favorites in the theme. This replaces the tag...

    <portal:favoritesLoop/>

    ...for enabling Organize Favorites functionality.

  2. Create a URL to Organize Favorites in the theme using the tag...

    <portal-navigation:urlGeneration>

    ...to wps.OrganizeFavorites.

  3. Create a My Favorite label to store the favorites by doing the following:

    1. Click...

    2. Select the Content Root page title

    3. Click New Label.

    4. Create a label called My Favorites.

    5. Assign privileged user access to all authenticated users.

    6. Click OK when you have finished.

    7. Click...

        Portal Settings | Custom Unique Names

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

    9. Click OK when you have finished.

    10. Click...

    11. Add a page parameter key of Favorites with a value of Yes.

  4. Add <portal-logic:if/> tags with the pageBookmarkable attribute set to true to pages that you want to be able to bookmark.

 

Improve the performance of themes

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

 

Use WCM-managed IMG in Portal Theme

  1. Upload the image to image component.

  2. Use an RTE component or element to create a link to the image component

  3. Open the code view in the RTE

  4. Copy the url to the image. It should look like something like this...

      /wps/wcm/myconnect/52346a00405832c59c67bc096aef9bce/mytheme.gif?MOD=AJPERES

  5. Use the url in your portal theme.

 

Parent topic

Customizing the portal

 

Related tasks


Importing a theme
Deploying the theme
Creating a new skin
Enabling automatic JSP reloading
Supporting new clients
Supporting new markup languages
Changing text information
Enabling the Organize Favorites portlet in themes

Related reference

Using the color palette in themes
Performance guidelines for themes and skins

Related information



Changing the page help