setupTheme (Tag Library Documentation Generator

Overview

Library

Tag

Help

FRAMES NO FRAMES

pui
Tag setupTheme

The Sun Java Web UI Components rely on resource files, including CSS stylesheets and JavaScript files, to render correctly. These resources are collectively known as a "Theme" and are bundled together in a Jar file. All SJWUIC components render CSS selectors that are defined on the Theme's basic stylesheet, and many rely on a common JavaScript library, so every HTML page that containing SJWUIC components must include a links to the core CSS stylesheet and JavaScript files. The pui:setupTheme tag can be used to print those links on the Portlet aggregation page.

The pui:setupTheme tag is a JSP tag that requires neither JSF, nor the SJWUIC library. It prints the same links to JavaScript files and CSS stylesheets as the SJWUIC ui:head component in terms, and is intended for scenarios where that component cannot be used.

HTML Elements

The pui:setupTheme tag renders a <link> element for the primary stylesheet associated with the theme and - if the browser client is Internet Explorer - an second <link> with additional styles needed for that browser. A <script> element with a reference to the file with JavaScript functions for the main form components is also written.

Configuring the portal server

Configure the portal server as follows:

Ensure that portletSetup.jar is in the classpath of the web application in which the portlet aggregation page ("the desktop") resides.
Ensure that the desired theme jars (for example, suntheme.jar) is in the classpath of the desktop, as well as in the classpath of any web application that provides a portlet that relies on the theme(s).
The theme resources that the browser needs to download are in the theme jar file. At least one web application on the portal server (for example, the desktop) must make these files available. You can either configure the application to run the ThemeServlet (recommended), or explode the archive into that application. It is possible to configure the ThemeServlet to run in a non-JSF application, if desired. See below for more details.

Configuring the `pui:setupTheme` Tag

Place the tag so that its output is rendered inside the HTML <head> element of the generated page (where you would normally place JavaScript and CSS references).

If more than one Theme is available, you may specify which Theme to use by setting the value of the themeName attribute to the name of the Theme, for example suntheme.

You must specify all locales that the SJWUIC portlets support. To determine the supported locales, examine the faces-config.xml files of the SJWUIC portlet web applications. Examine the <locale-element> and construct a string starting with the value of the <default-locale> element, followed by the value of any <supported-locale> elements, separated by commas. For example, if the configuration file contains

        <locale-config>
          <default-locale>en</default-locale>
          <supported-locale>de</supported-locale>
          <supported-locale>sv</supported-locale>
          <supported-locale>fr</supported-locale>
          <supported-locale>ko</supported-locale>
          <supported-locale>ja</supported-locale>
          <supported-locale>zh_TW</supported-locale> 
        </locale-config>

the value of locales will be

en, de, sv, fr, ko, ja, zh_TW

If the Portlet aggregation page runs in a JSP-compliant container, no further configuration is necessary. If the aggregation page is in a non-compliant container such as the Sun Portal Server version 6.3 or lower, you must specify a sessionDataStrategyClass. For Sun Portal Server 6.3.X use com.sun.web.ui.portletSetup.PSSessionDataStrategy.

Configuring the ThemeServlet in the aggregation application

The pui:setupTheme tag generates HTML elements that contain references to resources that must be extracted from the Theme jar. You must configure the ThemeServlet to serve these resources. This class is included in portletSetup.jar and can be used without the JSF runtime or the SJWUIC runtime.

Enter the following servlet declaration into the deployment descriptor of the application:

    <servlet>
        <servlet-name>ThemeServlet</servlet-name>
        <servlet-class>com.sun.web.ui.theme.ThemeServlet</servlet-class>
        <load-on-startup>2</load-on-startup>

        <init-param>
        <param-name>com.sun.web.ui.locales</param-name>
        <param-value>
        </param-value>[LOCALES]</init-param>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>ThemeServlet</servlet-name>
        <url-pattern>/theme/*</url-pattern>
    </servlet-mapping>

where [LOCALES] should be replaced with the value that is used for the locales attribute of the tag, and the load-on-startup with whatever is appropriate for your application. When running in a SJWUIC application, the ThemeServlet gets the supported locales from the JSF configuration file; since this time the ThemeServlet is not in a JSF application, the locales must be specified like this.

Serving Theme resources from one single web application

If a server is configured to run more than one web application that uses the same Theme(s), and if all of them support the same set of locales, then performance will be improved by providing the Theme resources through one of the applications only.

To do this, remove the ThemeServlet declaration from all web applications but one (leave the one in the aggregation application). In each of the applications where the ThemeServlet has been removed, set the value of the context attribute com.sun.web.console.resource_path to the path of the web application that still declares the ThemeServlet, for example /portalApp. (There are several ways to set a context attribute. One variant is to create a Servlet Listener and have it set the attribute when when the application is loaded.)

Themes consist of both of resources that are used directly by the Java classes at runtime (for example, a message) and resources to which the Java classes print paths, but which are then requested by the web application user's browser (for example, a stylesheet). This means that the Theme jars must be available to all applications, not just the one with the ThemeServlet.

Examples

Example 1: Sun Portal Server 6.3.X using suntheme, English is the sole supported locale

 
      <pui:setupTheme themeName="suntheme" 
                      locales="en"
                      sessionDataStragegyClass="com.sun.web.ui.portletSetup.PSSessionDataStrategy" />

Example 2: Pluto Portlet container using defaulttheme, Swedish is default and English is supported.

 
      <pui:setupTheme themeName="defaulttheme" 
                      locales="sv, en"/>

Tag Information
Tag Class	com.sun.web.ui.portletSetup.SetupThemeTag
TagExtraInfo Class	None
Body Content	empty
Display Name	None

Attributes
Name	Required	Request-time	Type	Description
themeName	true	true	`java.lang.String`	Specify the name of the theme to use, for example `suntheme`.
supportedLocales	true	true	`java.lang.String`	Specify the default locale of the SJWUIC applications, followed by any other supported locales separated by commas, for example `sv, en, fr`.
sessionDataStrategyClass	false	true	`java.lang.String`	Specify a value for this tag only if the JSP container is not fully JSP compliant. If you are using Sun Portal Server 6.3.X set the value to `com.sun.web.ui.portletSetup.PSSessionDataStrategy`.

Variables
No Variables Defined.