| Red Hat Portal Server 1.0: Portal Server Developer Guide | ||
|---|---|---|
| Prev | Chapter 3. Developing on Portal Server | Next |
The Concepts chapter of this guide described how styling takes place for a typical Portal Server deployment. This section delves into details of how styling is implemented and offers several methods that a developer can use to alter the styling of a Portal. First, we explore Portal Server Themes, which is a persistent mechanism for customizing a Portal's look and feel. When custom styling objectives fall beyond the capability of Themes, then Portal Server provides additional global styling control via XSLT and CSS. This section also provides guidelines for making more wholesale structural changes such as adding changing or creating new page layouts.
While Portal Server can be made to render to pervasive devices such as cell phones and networked PDAs, the majority of this section will limit its scope to rendering output for browsers using HTML.
A Theme is a set of look and feel options encapsulated within a com.arsdigita.portalserver.Theme domain object. Here is the list of properties available for a Theme:
Theme Name
Theme Description
Context Bar Color
Context Bar Text Color
Active Tab Color
Active Tab Text Color
Inactive Tab Color
Inactive Tab Text Color
Top Rule Color
Bottom Rule Color
Portlet Header Color
Portlet Header Icon Color
Portlet Border Color
Portlet Border Style
Portlet Header Text Color
Page Background Color
Page Background Image
Narrow Column Background Color
Page Text Color
On the local admin page for every mounted Portal instance, is a Themes tab. Selecting this tab presents the user with list of available Themes installed on the system, with a radio selection button next to each. The theme currently in use is pre-selected in this view. To change the Theme, the user chooses the desired theme by selecting the appropriate radio button, and then clicking on the Apply Theme submit button. Note that Themes only apply to normal Portal views - not administration pages.
The Web Application Framework Persistence layer maps the fields in the Themes database table to the getter/setter methods in the Theme domain class. When a Portal page is rendered, the theme associated with the portal is retrieved, and the values for the theme are written into a tag delimited styleblock element in the output XML for the page, as a CDATA segment. This xml block is then matched in the XSL transformation process, and the style values are passed into the head section of the HTML output as a CSS style section. The cascading precedence rules of CSS allow this style section to override the default style values for a Portal, which reside in the CSS sheet deployed with Portal Server.
In this version of Portal Server, creating new theme options requires either compiling the new theme into the deployment by specifying the new theme in the Portal Server Initializer class, or by storing the new theme directly in the database using PL/SQL statements. In a near future release of Portal Server, a user interface for building themes will be available, and be linked off of the Theme tab in the Portal's local administration page.
Compiling a new Theme — The description of a new theme can be added to the com.arsdigita. portalserver.Initializer class. This class is where the default Themes that ship with Portal Server are declared. To add an additional Theme, just add another Theme specification to the buildDefaultThemes() method in this file using an existing Theme definition as a guide. The drawback to this method, is that the buildDefaultThemes() method only runs at initial server startup, so for this method to work, the Portal Server data tables would have to be dropped - not a workable solution after the server has been up and running in production use. A workaround to this would be to add just the new theme description to a new Initializer class, using the com.arsdigita.portalserver.Initializer as a guide, and then register its complete package path in the enterprise.init file, and then bounce the server. This enterprise.init entry should then be removed, as subsequent server starts with the Initializer reference in place would generate multiple copies of the Theme being saved to the persistent store.
Installing a new Theme in the Database — In the database, a new Theme could be stored in the themes table directly, with the assistance of the DBA. The SQL file that creates the themes table can be found under the WEB-INF directory of the Portal Server deployment in the sql/pserv/ddl/ directory.
XSL and CSS are both used to render the final output of a Portal view. XSL is used within the Portal Server to structure a Portal page, and to order the components on the page. CSS is used for cosmetic styling like colors and borders. The XML output from the portal before XSLT transformation is primarily raw data with associated attributes. The XSL sheet assembles the page for delivery to the browser by transforming the XML using a set of template matches, and replacing XML sections with appropriate HTML. In Portal Server, some template matches correspond to areas of the final rendered page, such as Header, Body, Footer, etc. Others are for particular components within a page area. Some templates are sensitive to attributes associated with the XML tag that they match; for example, an administration portal page has different visual elements than a regular portal page, so the admin portal page tag includes an attribute that identifies it as such, and a different match rule is invoked in the XSL sheet.
The most common reason to change the default styling of Portal Server is to customize the Portal page header and Portal page color choices to have a deployment conform with an existing site's look and feel. While it is sometimes necessary to edit stylesheets to reach the desired look and feel, it is suggested that some of the run time mechanisms available through the Portal's local administration page for altering a Portal's look and feel, such as themes, be explored first.
See the tutorials section of this document for an example of how to alter a stylesheet.
The current implementation of Portal Server uses a common page structure with a header, a body, and a footer. This structure is primarily defined in the XSL for Portal Server. The header area of Portal pages is for a context bar with navigation aids and a sign-out icon, and such. The Portal and associated Portlets are rendered in the body section. It is possible that a Portal Server user may want to change the page structure, and this can be done by changing the XSL and CSS, but in doing so, it is possible that the styling attributes which the Themes class persists may not match elements of the new page structure, or that additional attributes are needed for Themes used with the new page structure. This can be reconciled by creating a class for the new theme. The new theme domain object would need to implement the com.arsdigita.portalserver.Theme interface, and have a PDL class that specified the new theme attributes and mapped them to the accessors in the new theme domain class. In addition, a data collection class representing a collection of the new theme objects would need to be implemented. This is a minor effort, and the existing ThemeCollection class can be used as a guide. Just as the current Theme class deployed with Portal Server implements a method that returns a collection of themes, the new theme domain class would need to do the same.
Portal Server currently provides 5 Portal layouts, that include most common 2 and 3 column Portal views, as well as a single column option. There is no UI for adding a new layout, but if a user really needed another layout option, it could be done. Adding another Layout choice, such as a four-column layout would require re-compiling code. Performing this task would fall into the category of an 'advanced' modification, but is certainly possible. The following is a list of issues that would need to be addressed:
Most of the work would need to be done in com.arsdigita.portalserver.ui.admin.DisplayPane . The m_layoutNames array would need a new unique string describing the new layout added to it. This string should be chosen so that the number of characters is equal to the number of desired columns in the new layout. For example, a new four column layout could use "NNNN" to describe it. Then, farther along in DisplayPane, there is an inner class called LayoutListModel. The name of the new layout that was added to m_layoutNames above, would need to be added to the vector in this inner class.
Next, the XSL stylesheet for Portal Server, portalserver.xsl would have to be modified to work with the new layout. There are two places in the stylesheet that would need to be changed. The first is where the link image is determined. There is a series of template matches for bebop:link and bebop:label in the stylesheet, that checks the class attribute for the layout strings defined in the m_layoutNames array in DisplayPane. The template match lines look like: xsl:template match="bebop:link[@class = 'NWN']". Two new template match blocks would need to be added that associate an image for the new layout when it is selected, and when it isn't. The existing template match blocks for these components can be copied with the new layout name added, and then the existing images could be used as a guide for creating new images for the new layout. Finally, farther down in the portalserver.xsl file, there is a series of template matches for bebop:portal each with a style attribute that corresponds to a layout by using the layout string name again. A new bebop:portal match would need to be added with the style attribute string the same as the new layout name. Then within this template block, the layout would actually be specified.
Portal Server uses XSLT in its rendering pipeline, so supporting current and future pervasive device user agents such as WAP enabled cell phones and PDAs is as simple as writing a stylesheet for the target device, and having the main Portal Page include a stylesheet attribute for the user agent.