6.2. Portlet Descriptors

The following sections describe the descriptors that define portal objects, such as portals, pages, portlet instances, windows, and portlets. Refer to Section 5.2, “Tutorials” and Section 6.4, “Descriptor Examples” for examples on using these descriptors within a portlet application.

6.2.1. *-object.xml Descriptors

The *-object.xml descriptors define portal instances, pages, windows, and the window layout. You can define several files if you want to split them into many files, they just all have to end with '-object.xml'. As well, themes and layouts for specific portal instances, pages, and windows, can be defined. The following example defines a portlet window being added to the default page, in the default portal. For advanced functionality using these descriptors, refer to Section 6.4, “Descriptor Examples”:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portal Object 2.6//EN"
   "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
   <deployment>
      <parent-ref>default.default</parent-ref>
      <if-exists>overwrite</if-exists>
      <window>
         <window-name>HelloWorldJSPPortletWindow</window-name>
         <instance-ref>HelloWorldJSPPortletInstance</instance-ref>
         <region>center</region>
         <height>1</height>
      </window>
   </deployment>
</deployments>
  • <deployments>...</deployments>
    The <deployments> element encapsulates the entire document, and is a container for <deployment> elements. Multiple deployments can be specified within the <deployments> element.
  • <deployment>...</deployment>
    The <deployment> element specifies object deployments, such as portals, pages, windows, and so on.
  • <if-exists>...</if-exists>
    The <if-exists> element defines the action to take if an instance with the same name already exists. Accepted values are overwrite and keep. The overwrite option destroys the existing object, and creates a new one based on the content of the deployment. The keep option maintains the existing object deployment, or creates a new one if it does not exist.
  • <parent-ref>...</parent-ref>
    The <parent-ref> element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The <parent-ref> element tells the portal where the portlet appears. The syntax for the <parent-ref> element is portal-instance.portal-page.
    In the example above, a window is defined, and assigned to default.default. This means the window appears on the default page, in the default portal.
  • <window>...</window>
    The <window> element defines a portlet window. The <window> element requires an <instance-ref> element, which assigns a portal instance to a window.
  • <window-name>...</window-name>
    The <window-name> element defines the unique name given to a portlet window. This can be named anything.
  • <instance-ref>...</instance-ref>
    The <instance-ref> elements define the portlet instances that windows represent. This value is the ID of a portlet instance, and must match the value of one of the <instance-id> elements in the WEB-INF/portlet-instances.xml file.
  • <region>...</region>
    <height>...</height>
    The <region> and <height> elements define where the window appears within the page layout. The <region> element specifies where the window appears on the page. The <region> element often depends on other regions defined in the portal layout. The <height> element can be assigned a value between one and X.
The previous *-object.xml example makes reference to items found in other descriptor files. The following diagram illustrates the relationship between the portlet.xml, portlet-instances.xml, and *-object.xml descriptors:

Are *-object.xml descriptors required?

Technically, they are not. The portal object hierarchy, such as creating portals, pages, instances, and organizing them on the page, can be defined using the management portlet, which is accessible to JBoss Portal administrators.