With the addition of the new Theme and Layout API it now simple to roll in your own custom layout and theme to change the look and feel of JBoss Portal. We took extra care to make it simple for you to implement your own custom layouts/themes and at the same time, separate the presentation from the business layer. This chapter will walk you through setting up and deploying your own custom layout and theme, making use of the this API.
Note
For the remainder of this chapter, a Theme is considered to be the CSS stylesheet that affects the "skin" of the layout. A Layout is the HTML markup used to control the placement of portlets on a page.
Themes and layouts are bundled together inside a war file with some additional XML descriptors and then dropped in the deploy directory of the portal. The example for this chapter can be downloaded from here. Once deployed, it will look like this:
The first step is to create a layout WAR file with all the necessary xml descriptors, images, and stylesheets.
myLayout.war |- simple-sample.css |-/images |-/layouts |- twoColumns.jsp |-/WEB-INF |- jboss-web.xml |- portal-layouts.xml |- portal-themes.xml
The XML descriptors explained:
portal-layouts.xml - Describes the layout name and files that should be accessed by the renderer. Here, our example is assigning a name to our layout and a reference to the file that should be used. In our example, we are only using one layout as such:
<layouts> <layout> <name>2ColumnLayout</name> <uri>/layouts/twoColumns.jsp</uri> </layout> </layouts>portal-themes.xml - Describes the stylesheet that should be used for our layout.
<themes> <theme> <name>simple-sample</name> <link href="/simple-sample.css" title="" rel="stylesheet" type="text/css" media="screen" /> </theme> </themes>jboss-web.xml - Describes the context-root of our war file containing the theme and layout.
<jboss-web> <context-root>/myLayout</context-root> </jboss-web>
The layout JSP explained:
Below we have our jsp that handles the positioning of the portlet windows in their assigned regions and also references the stylesheet we declared in portal-themes.xml above.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"><head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/> <p:theme themeName='simple-sample' /> <body> <!-- header table --> <table class="headerTable"> <tr> <td align="center"> <img src="/myLayout/images/logo.gif" /> </td> </tr> </table> <!-- center table with columns --> <table width="100%" bgcolor="#FFFFFF"> <tr> <td class="leftColumn"><p:region regionName='left'/></td> <td class="centerColumn"><p:region regionName='center'/></td> </tr> </table> <!-- footer table - HTML ommited for brevity. --> </body> </html>
There are two tags here that are important to note:
<p:theme themeName='simple-sample' /> - Maps to the theme declared in portal-themes.xml
<p:region regionName='<regionName>'/> - Defines regions where the assigned portlet windows will be places; left, center, right are acceptible values.
The actual simple-sample.css file can include any styles you have defined for your theme. It is advisable that you follow the JSR-168 specification in defining your stylesheets.
All that is left to do now is to let the Portal know you will be using this new theme and layout combination. To do this, you will have to edit $PORTAL_HOME/portal-core.war/WEB-INF/default-portal.xml.
Setting the Layout: You will have to modify the xml descriptor to point to the new layout you declared in portal-layouts.xml, using the layout name above as the value:
<property> <name>org.jboss.portal.property.layout</name> <value>2ColumnLayout</value> </property>Setting the Render Class: Our example layout uses the org.jboss.portal.property.renderSet.divRender class. Describing the different render classes bundled in the distribution, is beyond the scope of this document. For now, edit the following as it is the class we are using:
<property> <name>org.jboss.portal.property.renderSet</name> <value>divRenderer</value> </property>
Now all that is left to do, is to drop in this archive in to the /deploy directory where JBoss Portal is deployed and navigate to the homepage to see it.