Chapter 2. XML descriptors

Chapter 2. XML descriptors
Prev		Next

Thomas Heute

<theute@jboss.org>

2.1. Introduction

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

2.2. /WEB-INF/jboss-portlet.xml

Here is a sample took from the forums portlet:

<portlet-app>
   <app-name>forums</app-name>
   <portlet>
      <portlet-name>ForumsPortlet</portlet-name>
      <security>
         [...]
      </security>
   </portlet>
</portlet-app>

First must be defined an application name, this will be used to create a reference to a portlet in the other descriptors. Then if some extra information are needed because you are using specific features of JBoss Portal, you need to add those details in this file, the portlet-name must be the same as defined in portlet.xml. (The security tag is explained in the security chapter of this documentation).

2.3. /WEB-INF/portlet.xml

This file is used to declare the portlets of your application, following is an example of such a file

<?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>UserPortlet</portlet-name>
      <portlet-class>org.jboss.nukes.core.portlet.user.UserPortlet</portlet-class>
      <supported-locale>en</supported-locale>
      <supported-locale>fr</supported-locale>
      <resource-bundle>Resource</resource-bundle>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <portlet-info>
         <title>User portlet</title>
      </portlet-info>
   </portlet>
   <portlet>
      <portlet-name>CMSPortlet</portlet-name>
      <portlet-class>org.jboss.nukes.core.portlet.cms.CMSPortlet</portlet-class>
      <init-param>
         <description>Content Repository Type: (webdav|http)</description>
         <name>repository</name>
         <value>webdav</value>
      </init-param>
      <init-param>
         <description>WebDAV server username</description>
         <name>username</name>
         <value>root</value>
      </init-param>
      <init-param>
         <description>WebDAV server password</description>
         <name>password</name>
         <value>root</value>
      </init-param>
      <supported-locale>en</supported-locale>
      <resource-bundle>Resource</resource-bundle>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
         <portlet-mode>HELP</portlet-mode>
      </supports>
      <portlet-info>
         <title>CMS 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:

portlet-name a mandatory entry to give a name to this portlet
portlet-class a mandatory entry to specify the class of the portlet
supported-locale optional entries to specify the supported languages (two letter country code)
resource-bundle an optional entry to specify the name of the resource bundle file (.properties)
init-param optional entries to give parameters to the portlet
supports/mime-type optional entries to specify all the supported mime-types
supports/portlet-mode optional entries to specify all the supported modes, VIEW, HELP, EDIT and/or custom modes
portlet-info/title optional entry to define a title to the portlet

2.4. portlet-instances.xml

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>UserPortletInstance</instance-name>
      <component-name>UserPortlet</component-name>
      <preferences>
         <preference>
            <name>one</name>
            <value>1.5</value>
         </preference>
         <preference>
            <name>two</name>
            <value>2.5</value>
            <read-only>true</read-only>
         </preference>
         <preference>
            <name>three</name>
            <value>3.5</value>
            <read-only>true</read-only>
         </preference>
      </preferences>
   </instance>
   <instance>
      <instance-name>CMSPortletInstance</instance-name>
      <component-name>CMSPortlet</component-name>
   </instance>
</instances>

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

instance-name required to specify the name of the instance
component-name required and has to be defined in the portlet.xml
preferences optional to define preferences relevant to this instance of a portlet

2.5. *-page.xml

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 -page.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>forums</page-name>
      <window>
         <window-name>ForumsPortletWindow</window-name>
         <instance-ref>forums.ForumsPortlet.ForumsPortletInstance</instance-ref>
         <default>true</default>
         <region>left</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 page as you want, this is how a page is define:

page-name required element to define the name of a page
window required element to define a window
- window-name required element to define the name of a window
- instance-ref required element, it must refers to an existing portlet instance. Notice how the name is decomposed, first you have the application name as defined in jboss-portlet.xml, the name of the portlet (as defined in portlet.xml) another dot and finally the name of the portlet instance (as defined in portlet-instances.xml.
- default optional element, it defines if this window should be the default window (and will occupy most of the space on the screen.
- region required element, it defines where on the theme, the window should be displayed, only the documentation of the theme can define what region exists for this specific theme.
- height required element, this integer defines where the window should be displayed compare to the others in a same region. The higher the number is the higher in the theme it will be displayed. If two windows have the same height value then the windows will be randomly placed.

2.6. *-portal.xml

Those files are used to define different portals. 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>

      <page>
         <page-name>test</page-name>
         <window>
            <window-name>DefaultPortletWindow</window-name>
            <instance-ref>portal.DefaultPortlet.DefaultPorltetInstance</instance-ref>
            <default>true</default>
            <region>left</region>
            <height>0</height>
         </window>
         <window>
            <window-name>TestPortletWindow</window-name>
            <instance-ref>portal.TestPortlet.TestPortletInstance</instance-ref>
            <region>left</region>
            <height>1</height>
         </window>
         <window>
            <window-name>PreferencesPortletWindow</window-name>
            <instance-ref>portal.PreferencesPortlet.PreferencesPortletInstance</instance-ref>
            <region>left</region>
            <height>2</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:

portal-name this is a required element to define the name of a portal.
supported-modes all the supported modes at the portal level, you can then specify for each instance the supported modes for a specific portlet.
supported-window-states all the supported window states at the portal level. You can add your own window states here.
pages to define the pages of your portal, the syntax is the same as in the -page.xml files.

Prev	Up	Next
Chapter 1. JSR168 portlets	Home	Chapter 3. Portal urls