|
|
Portal Guide |
This chapter explains how to use portal themes to control the look and feel of a Director portal application. It contains the following sections:
A portal theme is a set of visual characteristics that apply to an entire Director portal application. Once you set the theme for a portal application, the settings associated with the theme apply globally. These settings can potentially change the appearance of portal pages (both PID pages and JSP pages) and portal components, as well as the appearance of user personalization and group pages. Themes provide a simple way to ensure a consistent appearance throughout a portal application.
Predefined themes Director ships with several predefined themes:
These themes are defined in the portal_core_resource.jar.
TIP: To see what these themes look like, try displaying the ThemeTester.html page, which is provided in the portal-page folder in the portal_core_resource.jar.
Custom themes You can also create your own custom themes. To do this, you use the Portal Themes Wizard in Workbench.
For details on using the Portal Themes Wizard, see
Creating Custom Themes.
Contents of a theme A portal theme consists of several files:
All of the files associated with a portal theme must be stored in a theme folder. The theme folder is a subdirectory of the portal-theme directory within a resource set. The name of the theme folder provides a key for the theme and uniquely identifies the theme.
For example, here is what the directory structure might look like for two sample themes, BasicBlue and BasicGreen:
...\portal-theme\ \BasicBlue theme.xml theme.css \images edit.gif edit_mousedown.gif edit_mouseover.gif minimize.gif minimize_mousedown.gif minimize_mouseover.gif preview.jpg thumbnail.jpg ...etc. \BasicGreen theme.xml theme.css \images edit.gif edit_mousedown.gif edit_mouseover.gif minimize.gif minimize_mousedown.gif minimize_mouseover.gif preview.jpg thumbnail.jpg ...etc.
For more information about where files are located in a resource set, see the section on Subdirectories for resources and Java classes in the Core Development Guide.
The theme descriptor file provides a display name, description, preview image file, and thumbnail image file for the theme. The theme descriptor file must have the name theme.xml. Each theme used by a portal application must have a separate theme.xml file.
These are the elements in the theme descriptor file:
|
Element name |
Description |
|---|---|
|
portal-theme |
The root node of the portal theme. |
|
display-name |
The name used to identify the theme in the user interface of a portal application. |
|
description |
The description of the theme. |
|
preview-image |
An image showing what the theme might look like. This is typically a screen shot showing how theme looks at display time. The path to this image could be a fully qualified URL or an URL that contains portal replacement strings.
|
|
thumbnail-image |
A smaller image showing what the theme might look like at display time. This image is typically used in user interfaces listing available themes. The path to this image could be a fully qualified URL or an URL that contains portal replacement strings.
|
Here is an example of a theme.xml file for a theme called BasicBlue:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portal-theme PUBLIC "-//SilverStream Software, LLC//DTD Portal Theme 4.0//EN" "portal-theme_4_0.dtd"> <portal-theme> <display-name>Basic Blue</display-name> <description>Basic Blue</description> <preview-image>$RESOURCE_URL$/portal-theme/BasicBlue/images/preview.gif </preview-image> <thumbnail-image>$RESOURCE_URL$ /portal-theme/BasicBlue/images/thumbnail.gif </thumbnail-image> </portal-theme>
The theme.css file for a theme is a standard cascading style sheet (CSS) that will work in Netscape 6 and Internet Explorer 5 (and beyond). It includes class definitions that can be used to alter the display of portal pages and components.
Each of the themes that ships with Director includes a theme.css that defines a set of standard Director classes. These classes begin with the s3- prefix. You can define new classes to define your own styles, and you can edit the settings for the predefined classes.
Some of the classes in a theme.css file can be applied anywhere within a portal page or component. These classes begin with a period:
.s3-fontSmall {
font-size : 9pt;
}
Other classes apply to a particular HTML tag. These classes specify the HTML tag as a prefix:
A.s3-Anchor:hover {
text-decoration : underline;
color : #003366;
}
By convention, each of the standard Director classes specifies values for a common set of HTML properties. However, a class definition need not specify values for all of the possible HTML properties normally associated with the class.
Some of the standard classes for the installed themes use the prefix x- to comment out certain property settings.
.s3-componentContainer {
x-border-style : solid;
x-border-color : red;
x-border-width : 2px;
x-width:600;
}
When the browser sees a property that it does not recognize, it simply ignores it.
Many of the standard classes define simple fonts and colors. But some of them are much more complex. In particular, the styles defined for portal components give the theme developer a great deal of control over the runtime display of components on a page.
For details on using the component styles to theme-enable a component, see
Creating components that are theme-enabled.
To create a new CSS file, you should save an existing file with a new name and begin editing that file. You can define new classes to define your own styles and edit the settings for the standard Director classes (those classes that begin with the s3 prefix). However, you should not remove or rename any of the standard classes. These classes are required by many of the core components that ship with Director.
If you decide to create your own custom classes, you should use these classes consistently throughout your application. In other words, each theme should provide appropriate settings for each of these custom classes, just as the installed themes provide settings for each of the standard Director classes.
The theme.css for each of the themes with Director defines several different predefined styles. These styles are grouped according to the types of display characteristics they alter:
A theme can include preview and thumbnail images, which give the user an idea what the theme will look like. A theme can also include images that actually appear when the theme is displayed at runtime. These can include background and foreground images, as well as theme option images, which control the appearance of portal options.
The theme preview image file is typically a screen shot showing what a theme looks like at display time. Here is the preview image file for the OrangeFlame theme:
The size of the preview image should be 320x320.
The thumbnail image file is a smaller image that shows what a theme looks like.
This image is typically used to list available themes in a user interface. The size of this preview image should be 45x45.
Themes can alter the appearance of portal options. For example, suppose a component title bar provides buttons to allow the user to edit, minimize, or restore the component. Each button can have several images associated with it so that the button image changes in response to user events. A theme can alter the image for each user event, giving a consistent look when the user changes the theme.
Each theme can supply a unique set of images for the various events associated with a portal option. However, the file names for these images should be the same in each portal theme. By using a consistent naming convention across themes, you can ensure that each user event will have an image to display regardless of which theme has been selected. For example, the Edit option associated with a component could have an image called edit_onmouseover.gif to handle the edit user event. In this case each theme supported by the application would need to include a file with the same name. This would ensure that the onmouseover event always has an image to display for each theme.
Portal pages can provide support for themes. To allow a PID or JSP page to alter its appearance when a user selects a new theme, you need to make some changes to the source for the page.
To create a page that is theme-enabled, you need to:
Include a <link> tag in the head section of the page that references the currently selected theme CSS file.
For details about including the link in a JSP page, see
Including the CSS link in a JSP page. For details about including the link in a PID page, see
Including the CSS link in a PID page.
Add HTML tags or portal components to the page that take advantage of the classes defined in the theme CSS file. By mapping your tags to classes in the CSS file, you can ensure that these tags will alter their appearance according to the display characteristics of the currently selected theme. For example, you might want to map each anchor tag in your page to the s3-anchor class in the CSS file:
<p><a class="s3-anchor" href="http://www.novell.com">link</a> that changes styles on a hover.</p>
You can use the standard Director class definitions (those that have names that begin with s3) or use custom class definitions that you define in the CSS file.
To include a <link> tag in the head section of a JSP page that references the currently selected theme, you need to use the getThemeLink tag.
Here's an example that shows how this is done:
<html> <head> <title>My Theme-Enabled Page</title> <%@ taglib uri="/portal" prefix="ep" %> <ep:getThemeLink /> </head> ...
The getThemeLink tag causes a <link> tag to be added to the generated HTML for the page. The <link> tag includes a path to the CSS file for the theme. The theme folder in the path is set to the selected theme. For example, when the user selects the BasicBlue theme, the <link> tag looks something like this:
<html> <head> <title>My Theme-Enabled Page</title> <lnk rel=`stylesheet' type="text/css" href=`http://localhost/Director/MyEar/Portal/main/resource/portal-theme/BasicBlue/theme.css'/> </head> ...
To include a <link> tag in the head section of a PID page that references the currently selected theme, you need to use the s3-component tag to add the PortalUrlHelper component to the page. The argument to the PortalUrlHelper component includes the syntax for the <link> tag.
Here's an example that illustrates how this is done:
<html> <head> <title>My Theme-Enabled Page</title> <s3-component id="PortalUrlHelper" instance="Helper" SUBST_STRING="<link rel='stylesheet' type='text/css' href='$THEME_URL$/theme.css'/>"/> </head> ...
The PortalUrlHelper component causes a <link> tag to be added to the generated HTML for the page. The <link> tag includes a path to the CSS file for the theme. The theme folder in the path is set to the selected theme. For example, when the user selects the BasicBlue theme, the <link> tag looks something like this:
<html> <head> <title>My Theme-Enabled Page</title> <lnk rel=`stylesheet' type="text/css" href=`http://localhost/Director/MyEar/Portal/main/resource/portal-theme/BasicBlue/theme.css'/> </head> ...
A portal component can use most of the style definitions in the theme.css file. For example, an HTML component might use one or more font or color styles to alter the appearance of text or controls. In the example shown below, the HTML table generated by a component uses a theme-specific font style. It also uses two numbered color styles to alternate the color of rows:
<table class="s3-fontExtraSmall" width="99%" border="0" cellspacing="0" cellpadding="1">
<tr class="s3-table-row-even">
<td width="40%"> Bill Lumbergh</td>
<td width="40%">781-555-1171</td>
<td width="20%"><div align="center"></div>
</td>
</tr>
<tr class="s3-table-row-odd">
<td> Peter Gibbons </td>
<td>781-555-3457</td>
<td><div align="center"></div>
</td>
</tr>
<tr class="s3-table-row-even">
<td> Michael Bolton </td>
<td>781-555-3566</td>
<td><div align="center"></div>
</td>
</tr>
<tr class="s3-table-row-odd">
<td> Milton Waddams </td>
<td>781-555-3442</td>
<td><div align="center"></div>
</td>
</tr>
<tr class="s3-table-row-even">
<td> Samir Nayeenanajar </td>
<td>781-555-3316</td>
<td><div align="center"></div>
</td>
</tr>
</table>
An HTML component could use string concatenation techniques in the getComponentData() method to generate this data. For an XML component, the styles would be specified in an XSL style sheet, as shown below:
<!-- Alternate the color of each row in the table --> <xsl:template match="employee"> <xsl:choose> <xsl:when test="position() mod 2 = 1"> <xsl:call-template name="employee_data"> <xsl:with-param name="StyleClass">s3-backgroundColor3</xsl:with-param> </xsl:call-template> </xsl:when> <xsl:otherwise> <xsl:call-template name="employee_data"> <xsl:with-param name="StyleClass">s3-backgroundColor5</xsl:with-param> </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:template>
The runtime display of a portal component is controlled by a portal decorator. A portal decorator is a Java class that builds the various display elements for a component on a page. Director provides a default decorator class called EboDefaultPortalDecorator, which is in the com.sssw.portal.core package.
To render the title bar, body, and footer for a portal component, the default decorator generates three separate HTML tables. Each of these tables uses class definitions provided in the theme.css file to ensure that the display is appropriate for the currently selected theme.
The following extract from the source code for EboDefaultPortalDecorator class shows how the standard component class definitions are used to render a component. Each class name defined in the theme.css file is highlighted in the source code:
package com.sssw.portal.core;
import com.sssw.portal.api.*;
public class EboDefaultPortalDecorator extends EboComponentDecorator{
public String decorateComponentData(EbiPortalContext context, String componentID, String componentData) {
return "<DIV class=s3-componentContainer>"
+ getTitleBarFragment(context)
+ getBodyFragment(context, componentData)
+ getFooterFragment(context)
+ "</DIV>";
}
public String getTitleBarFragment(EbiPortalContext context){
StringBuffer buffer = new StringBuffer("");
// Build the title bar for this component
// It is a table which consists of 1 row with 4 columns (leftBoder, leftContent, RightContent, rightBorder)
buffer.append("<table class=\"s3-titleBarContainer\" border=\"0\" cellspacing=\"0\" cellpadding=\"0\">\n");
buffer.append(" <tr>\n");
buffer.append(" <td class=\"s3-titleBarBorderLeft\"></td>\n");
buffer.append(" <td class=\"s3-titleBarContentLeft\">" +
getTitleBarContentLeft(context) + "</td>\n");
buffer.append(" <td class=\"s3-titleBarContentRight\">" +
getTitleBarContentRight(context) + "</td>\n");
buffer.append(" <td class=\"s3-titleBarBorderRight\"></td>\n");
buffer.append(" </tr>\n");
buffer.append("</table>\n");
return buffer.toString();
}
public String getBodyFragment(EbiPortalContext context, String contentFragment){
StringBuffer buffer = new StringBuffer();
buffer.append("<table class=\"s3-bodyContainer\" border=\"0\" cellspacing=\"0\" cellpadding=\"0\">\n");
buffer.append(" <tr>\n");
buffer.append(" <td class=\"s3-bodyBorderLeft\"></td>\n");
buffer.append(" <td>" + contentFragment + "</td>\n");
buffer.append(" <td class=\"s3-bodyBorderRight\"></td>\n");
buffer.append(" </tr>\n");
buffer.append("</table>\n");
return buffer.toString();
}
public String getFooterFragment(EbiPortalContext context){
StringBuffer buffer = new StringBuffer();
buffer.append("<table class=\"s3-footerContainer\" border=\"0\"
cellspacing=\"0\" cellpadding=\"0\">\n");
buffer.append(" <tr>\n");
buffer.append(" <td class=\"s3-footerBorderLeft\"></td>\n");
buffer.append(" <td class=\"s3-footerContentLeft\">" +
getFooterContentLeft(context) + "</td>\n");
buffer.append(" <td class=\"s3-footerContentRight\">" +
getFooterContentRight(context) + "</td>\n");
buffer.append(" <td class=\"s3-footerBorderRight\"></td>\n");
buffer.append(" </tr>\n");
buffer.append("</table>\n");
return buffer.toString();
}
...
The CSS file for a theme divides the visual display of a component into several sections, as shown below:
To get a better understanding of how the CSS file for a theme is used to render a component, consider the OrangeFlame theme. Here's what the PhoneList component looks like when the OrangeFlame theme is selected:
The following illustration shows the PhoneList component with annotations indicating the display sections:
The theme.css file for OrangeFlame specifies background images for most of the display sections for a portal component:
The Director API provides two interfaces for working with themes:
EbiThemeManager provides methods for accessing EbiThemeInfo objects. EbiThemeInfo provides methods for retrieving various kinds of information about a theme, including its display name and description. The EbiThemeInfo interface also provides access to the URIs for a theme's preview and thumbnail images.
To access an EbiThemeManager object, you need to use the getThemeManager() method on the EboFactory class for the Portal subsystem.
|
|
Portal Guide |
Copyright © 2000, 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.
