Chapter 2. XML descriptors
Prev   Next

Chapter 2. XML descriptors

Thomas Heute

2.1. Introduction

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.

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

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).

2.3. /WEB-INF/jboss-app.xml

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

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

2.4. /WEB-INF/portlet.xml

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:

  • 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.5. 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>HelloWorldPortletInstance</instance-name>
      <component-ref>HelloWorldPortlet</component-ref>
   </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-ref required and has to be defined in the portlet.xml
  • preferences optional to define preferences relevant to this instance of a portlet

2.6. *-pages.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 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:

  • 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.
    • height required element, this integer defines where the window should be displayed compare to the others in a same region. The lower 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.7. *-portal.xml

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:

  • 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 -pages.xml files.
Prev Up Next
Chapter 1. JSR168 portlets Home Chapter 3. Portal urls