6.2.4. The portlet.xml Descriptor

The portlet.xml descriptor is the standard portlet descriptor covered by the JSR-168 Portlet Specification. Developers are strongly encouraged to read the JSR-168 Portlet Specification items covering the correct use of this descriptor, as it is only covered briefly in these sections. Normally the portlet.xml descriptor is packaged inside your portlet WAR file, alongside the other descriptors in these sections. The following example is a modified version of the JBoss Portal UserPortlet definition:
<?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
                          http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
      version="1.0">
   <portlet>
      <description>Portlet providing user login/logout and profile management</description>
      <portlet-name>UserPortlet</portlet-name>
      <display-name>User Portlet</display-name>
      <portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class>
      <init-param>
         <description>Initialize the portlet with a default page to render</description>
     <name>>default-view</name>
     <value>/WEB-INF/jsf/objects.xhtml</value>
      </init-param>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <supported-locale>en</supported-locale>
      <supported-locale>fr</supported-locale>
      <supported-locale>es</supported-locale>
      <resource-bundle>Resource</resource-bundle>
      <portlet-info>
         <title>User portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>
  • <portlet-app>...</portlet-app>
    The <portlet-app> element encapsulates the entire document. Multiple portlets can be specified using the <portlet-app> element.
  • <portlet>...</portlet>
    The <portlet> element defines one portlet that is deployed within this archive.
  • <description>...</description>
    The <description> element is a verbal description of the portlet's function.
  • <portlet-name>...</portlet-name>
    The <portlet-name> element defines the portlet name. It does not have to be the class name.
  • <portlet-class>...</portlet-class>
    The <portlet-class> element defines the Fully Qualified Name (FQN) of the portlet class.
  • <init-param>
       <name>...</name>
       <value>...</value>
    </init-param>
    The <init-param> element specifies initialization parameters to create an initial state inside your portlet class. This is usually used in the portlet's init() method, but not necessarily. Unlike a preference, an init-parameter is data that does not change at runtime and does not go into a database. If the value is changed in the descriptor, the change takes immediate effect after re-deploying the portlet. Multiple <init-param> elements can be used.
  • <supports>...</supports>
    The <supports> element declares all of the markup types that a portlet supports. Use the <mime-type> element to declare supported capabilities, for example, if the only outputs are text and HTML, use <mime-type>text/html</mime-type>. Use the <portlet-mode> element to define the supported portlet modes for the portlet. For example, all portlets must support the view portlet mode, which is defined using <portlet-mode>view</portlet-mode>.
  • <supported-locale>...</supported-locale>
    The <supported-locale> elements advertise the supported locales for the portlet. Use multiple <supported-locale> elements to specify multiple locales.
  • <resource-bundle>...</resource-bundle>
    The <resource-bundle> element specifies the resource bundle that contains the localized information for the specified locales.
  • <portlet-info>
       <title>...</title>
    </portlet-info>
    The <title> element defines the portlet's title, which is displayed in the portlet window's title bar.

The portlet.xml Example

This portlet.xml example is not a replacement for what is covered in the JSR-168 Portlet Specification.