JBoss Portal 2.0 RC2

The JSR 168 specification aims at defining porlets that can be used by any JSR168 portlet container also called portals. There are different portals out there with commercial and non-commercial licences. In this chapter we will briefly describe such portlets but for more details you should read the specifications available on the web.

As of today, JBoss portal is fully JSR168 1.0 compliant, that means that any JSR168 portlet will behave as it should inside the portal.

What is really important to know about such portlets is that when a page is displayed it is divided into two distincts parts, an action part on one portlet followed by rendering parts for every porlets displayed on a page. A portal just aggregates all the chunks of HTML rendered by the different portlets of a page.

1.2.2. Page composition

A portal can be seen as pages with different areas and inside areas, different windows and each window having one portlet.

To define your portals, you will need to create a few XML files in order to declare your portlet, portlet instances, windows, pages and then your portals.

Here is a sample taken from our HelloWorldPortlet (packaged in helloworld.war that you can download here.):

<portlet-app>
   <portlet>
      <portlet-name>HelloWorldPortlet</portlet-name>
      <security></security>
   </portlet>
</portlet-app>

portlet-name must be the same as defined in portlet.xml.

(The security tag is explained in the security chapter of this documentation).

This file is JBoss specific and identifies your application WAR file.

<jboss-app>
    <app-name>helloworld</app-name>
</jboss-app>

This file is used to declare the portlets of your application:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd /opt/SUNWps/dtd/portlet.xsd" version="1.0">
   <portlet>
      <portlet-name>HelloWorldPortlet</portlet-name>
      <portlet-class>org.jboss.portlet.helloworld.HelloWorld</portlet-class>
      <supported-locale>en</supported-locale>
      <resource-bundle>Resource</resource-bundle>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <portlet-info>
         <title>My HelloWorld Portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>

As you can see for any portlet you need to add a portlet tag, then you need to give extra information as follow:

After you defined all the portlets you need, you will need to define the instances that you will use.

<?xml version="1.0" standalone="yes"?>
<instances>
   <instance>
      <instance-name>HelloWorldPortletInstance</instance-name>
      <component-ref>HelloWorldPortlet</component-ref>
   </instance>
</instances>

Again the file is pretty simple, the instancestag includes instance elements with:

You defined your portlets then your instances of portlet, now let's put them together on a page, to do so you can create files with helloworld-pages.xml and put them either in the WEB-INF of a war file or in the deploy directory of JBoss.

Here is the page for the forums module as example:

<pages>
    <portal-name>default</portal-name>
    <page>
        <page-name>samples</page-name>
        <window>
            <window-name>HelloWorldPortletWindow</window-name>
            <instance-ref>helloworld.HelloWorldPortlet.HelloWorldPortletInstance</instance-ref>
            <default>true</default>
            <region>center</region>
            <height>0</height>
        </window>
    </page>
</pages>      

Again this is pretty straightforward. At first you need to define in which portal this page should belongs to (we will see later how to define a portal). Then you define the pages, you can define as many pages as you want, this is how a page is define:

Used to define different portal instances within the container. The files *-portal.xml can be include into a war file (WEB-INF directory) or directly in the deploy directory of JBoss.

<?xml version="1.0" encoding="UTF-8"?>
<portal>
   <portal-name>default</portal-name>
   <supported-modes>
      <mode>VIEW</mode>
      <mode>EDIT</mode>
      <mode>HELP</mode>
   </supported-modes>
   <supported-window-states>
      <window-state>NORMAL</window-state>
      <window-state>MINIMIZED</window-state>
      <window-state>MAXIMIZED</window-state>
   </supported-window-states>
   <pages>
      <default-page>default</default-page>
      <page>
         <page-name>default</page-name>
         <window>
            <window-name>CMSPortletWindow</window-name>
            <instance-ref>portal.CMSPortlet.CMSPortletInstance</instance-ref>
            <default>true</default>
            <region>left</region>
            <height>0</height>
         </window>
         <window>
            <window-name>UserPortletWindow1</window-name>
            <instance-ref>portal.UserPortlet.UserPortletInstance</instance-ref>
            <region>left</region>
            <height>0</height>
         </window>
      </page>

      <page>
         <page-name>admin</page-name>
         <window>
            <window-name>UserPortletWindow2</window-name>
            <instance-ref>portal.UserPortlet.UserPortletInstance</instance-ref>
            <default>true</default>
            <region>left</region>
            <height>0</height>
         </window>
         <window>
            <window-name>GroupPortletWindow</window-name>
            <instance-ref>portal.GroupPortlet.GroupPortletInstance</instance-ref>
            <region>right</region>
            <height>1</height>
         </window>
         <window>
            <window-name>AdminCMSPortletWindow</window-name>
            <instance-ref>portal.AdminCMSPortlet.AdminCMSPortletInstance</instance-ref>
            <region>left</region>
            <height>4</height>
         </window>         
      </page>
   </pages>
</portal>

This file is the descriptor of a portal, of course you can define several portals containing several pages. Here is how you define a portal:

Most of the time portals use very complicated urls, however it is possible to setup entry points in the portal that follow simple patterns.

Each portal container can contain multiple portals and within a givin portal, windows are organized in pages, a page simply being a collection of windows associated to a name.

Before reading this chapter you must know how to define a page and a portal, you can refer to the chapter about XML descriptors to have a better understanding of those notions.

Each portal container can contains multiple portals, also there is one special portal which is the default portal, i.e the one used when no portal is specified in particular.

It is possible to have multiple page per portal. As for portal there is a default page for a given portal. Once the portal has been selected, then a page must be used and all the windows present in that page will be rendered. The page selection mechanism is the following.

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.

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:

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:

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.

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.