Portal, Express Beta Version 6.1 Operating systems: i5/OS, Linux,Windows

Creating a new theme

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 Express, you will be able to easily 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.

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

1. 1. Create a new directory path using the predefined root themes, the type of markup, and the name of the new theme, for example: 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 directory. For example, you could copy the files from the /Portal theme. Note: If you use the Portal theme, also copy the resources under 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. 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. Next to the Themes directory, create a WEB-INF directory.
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. Create the subdirectory WEB-INF/tld.
7. Copy all tld files to the WEB-INF/tld directory.
8. Wrap the new theme as MyTheme.war using a ZIP compression tool.
9. To install the new theme in WebSphere Application Server:

   1. Open the application server admin console.
   2. Under Applications > Install New Application select 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. Make sure that the newly deployed web application is started.
10. To make the new theme available in WebSphere Portal Express:

    1. Use the Themes and Skins portlet under Administration > Portal User Interface. See Themes and Skins help for more information. 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

Deploying the theme

Enabling Organize Favorites functionality in custom themes

The "My Favorites" feature in WebSphere Portal Express 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.

• 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 to store the favorites by doing the following:

  • Click Administration > Portal User Interface > Manage Pages
  • Select the Content Root page title to select the Content Root page.
  • At the Content Root page, click New Label.
  • Create a label called My Favorites.
  • Assign privileged user access to all authenticated users.
  • Click OK when you have finished.
  • Click Portal Settings > Custom Unique Names.
  • Assign wps.My Favorites as a unique name to the My Favorites label you just created.
  • Click OK when you have finished.
  • Click Administration > Portal User Interface > Manage Pages.
  • Add a page parameter key of Favorites with a value of Yes.
• 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 Express includes a lightweight theme that demonstrates some of the design features that you could omit for better performance.