Application definition elements of the portal topology descriptor

Application definition elements

The <application-definition/> element describes the portal application, its components, page layout, and navigation. It is contained by the <ibm-portal-topology/> element in the portal topology descriptor.

Basic structure of the application definition

The following figure illustrates the elements of the application definition that are supported for this release. Figure 1. Elements in the portal application definition
<application-definition appID="" version="">     <title/>     <requires uniqueName="" version=""/>     <component-tree uniqueName="">       <portlet-definition uniqueName="">
         <title/>
         <resource-link name="" type="" portletApplication=""/>
      </portlet-definition>
      <portlet-entity uniqueName="" portletDefinitionRef="">
         <title/>
      </portlet-entity>
      <url-link uniqueName="" url="" absolute="" /> 
   </component-tree>

   <layout-tree>  
      <layout-element uniqueName="">  
         <title/> 
         <simple-container uniqueName="" orientation="">
            <window uniqueName="">
               <title/>
               <component-definition-ref/>
            </window>
         </simple-container>
      </layout-element>
   </layout-tree>

   <navigation-element uniqueName="" layoutElementRef="">       <title/>
      <preference>
         <value/> 
      </preference>  
      <url-mapping/>
      <parent-tree parentTreeRef="" ordinal=""/>
      <navigation-content uniqueName="" componentDefinitionRef="" windowRef=""/>
   </navigation-element>

</application-definition>
Other elements of the application definition that can be found in the ibm-portal-topology.xsd schema are not supported for this release. At a minimum, the application definition requires a title, a component tree, and a layout tree. The following sections describe the <application-definition/> element, its attributes, and its subelements.

Application definition

The <application-definition/> element defines one or more applications that are part of the package. Exactly one is required. The following attributes are used with this element.

appID

Required. Specifies a unique identifier for this portal application. The appID has no relationship with IDs in the portlet.xml. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

version

Required. Specifies the numerical version of the application. The format of the version is defined in the ibm-portal-base.xsd schema under the simple type for VersionString.

Title

Exactly one is required. The <title/> element provides a title for the application. If this is the lead application for a product, this title is displayed on the Welcome page when the user logs into the console. A lead application is the one that includes the <about-page/> element in the topology definition. Subcomponents of the product use the <PAA-ref/> element to specify the lead application to which they belong. The content of the <title/> element can be specified as a simple string element from the base schema. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content. For example:
  <title>
    <base:nls-string lang="en">Integrated Solutions Console Sample</base:nls-string>
  </title>
Requires

Optional, multiple allowed. The <requires/> element indicates the unique ID of a portal application that is a prerequisite for this application. Any prerequisites for the application must be already deployed. The application can have multiple prerequisites.
The following attributes are used with this element.

uniqueName

Required. Unique identifier of another application that must already be deployed on the server. This value must match the appID attribute from the <application-definition/> element of the required application's topology descriptor. Otherwise, deployment fails.

version

Required. Specifies the numerical version from the required application's <application-definition/> element. If the version is not identical to the required application's version string, deployment fails. Required.

The following example shows how the tree merge sample indicates the page layout sample as a prerequisite application.
<requires uniqueName="com.ibm.isclite.samples.PageLayout" version="6.1"/>
The following example shows the attributes for the <application-definition/> element of the page layout sample. These attributes are used as the values for attributes on the <requires/> element for the tree merge sample.
<application-definition appID="com.ibm.isclite.samples.PageLayout" version="6.1">
...
Component tree

Exactly one is required. The <component-tree/> element describes all portlets in the console module. The tree structure of the component definitions can be used for organizing the components in the portal application. There are no semantics associated with this organization and the portal may not respect this structure for organizing the actual portal resources corresponding to it. The following attribute is used with this element.

uniqueName

Required. Specifies a unique identifier for the component tree. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

The following elements make up the content of the <component-tree/> element.
<portlet-definition/>
Optional, multiple allowed. This element describes one portlet. The portlet can be included in the same archive or already deployed on the server.. A portlet definition refers to a portlet defined in a portlet.xml deployment descriptor in a portlet WAR file. A portlet can be associated with a window in a layout. In most cases, the application artifact is actually defined by its own deployment descriptor within the archive and the <resource-link/> element is used for referencing it so that it can be integrated into the portal application page layout and navigation. The following attribute is used with this element.

uniqueName

Required. Specifies a unique identifier for the portlet definition. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

The following element makes up the content of the <portlet-definition/>.
<title/>

Required, exactly one allowed. This element provides a title for the portlet definition. This title is not displayed in the console for this release. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content.

<resource-link/>
Required, exactly one allowed. This element provides a link to a portlet definition that is included in the PAA package or is already deployed separately in the portal. The following attributes are used with this element.

name

Specifies the name of the portlet as defined by the <portlet-name/> element in the portlet.xml. If the name of the portlet is not unique within the PAA, an additional portlet-application attribute must be specified.

type

The value static specifies that the resource must be available at the time the PAA package is deployed. This is the default and the only value that is supported for this release.

portletApplication

Specifies the ID attribute of the <portlet-app/> element in the portlet.xml. Since different PAA packages could have portlets with the same name, it is necessary to name space them.

The following example shows the <resource-link/> element for the page layout sample.
<resource-link name="PageLayoutPortlet1" 
       portletApplication="com.ibm.isclite.samples.PageLayout" type="static"/>
The following example is taken from the portlet.xml for the page layout sample to show the values needed for the previous <resource-link/> example.
...
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" 
             version="1.0" id="com.ibm.isclite.samples.PageLayout"
             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">
    <portlet id="PageLayout_Portlet1" >
       <portlet-name>PageLayoutPortlet1</portlet-name>
...
The next example is also from the page layout sample. In this example, the <resource-link/> uses values from a portlet that is already deployed to the portal. These values come from the portlet.xml of the portlet (TempPortlet) from the tree merge sample.
<portlet-definition uniqueName="com.ibm.isclite.TreeMerge.appElementDefinition.A">
   <title>
      <base:nls-string lang="en">TreeMergePortlet</base:nls-string>
   </title>                                   
   <resource-link name="TempPortlet" 
                  portletApplication="com.ibm.isclite.samples.TreeMerge" type="static"/>
</portlet-definition>  
<portlet-entity uniqueName="com.ibm.isclite.TreeMerge.appElement.B" 
                portletDefinitionRef="com.ibm.isclite.TreeMerge.appElementDefinition.A">
   <title>
      <base:nls-string lang="en">TempPortlet</base:nls-string>
   </title>
</portlet-entity>
<portlet-entity/>

Optional, multiple allowed. This element specifies an instance of a portlet definition with additional configuration values. The portlet entity's uniqueName is used by the <window/> element to place the portlet on the page. The portlet definition that is specified can reside in the current archive or already be deployed on the server.The following attributes are used with this element.

uniqueName

Required. Specifies a unique identifier for the portlet entity. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

portletDefinitionRef

Required. References the unique name of the portlet definition within the same topology descriptor file.

The following element makes up the content of the portlet definition.

<title/>

Optional, no more than one allowed. This element provides a title for the portlet entity. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content. This title is rendered in the portlet window.

<url-link/>
Optional and multiple elements are allowed. This element is used to include links to external URLs that are added to the console navigation . The following attributes are used with this element.

uniqueName

Required. Specifies a unique identifier for the url link. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

absolute

Optional. Indicates whether the URL is an absolute value (true) or relative value (false). Only absolute values are supported for this release and the default value is true.

url

Required. Specifies an external address or URL that will be added to the console navigation.

In the following example, the URL for a company support page is provided.
<url-link uniqueName="my.example.com.support.page" url="http://my.example.com/support" absolute="true"/> 
The following example shows part of the <component-tree/> element for the page layout sample with the first portlet definition and corresponding portlet entity.
<component-tree uniqueName="com.ibm.isclite.pagelayout.appTree">

           
   <portlet-definition uniqueName="com.ibm.isclite.pagelayout.appElementDefinition.A">
      <title>
         <base:nls-string lang="en">RowPortlet</base:nls-string>
      </title>
      <resource-link name="PageLayoutPortlet1" 
                     portletApplication="com.ibm.isclite.samples.PageLayout" type="static"/>
   </portlet-definition>  
   <portlet-entity uniqueName="com.ibm.isclite.pagelayout.appElement.A" 
                   portletDefinitionRef="com.ibm.isclite.pagelayout.appElementDefinition.A">
      <title>
         <base:nls-string lang="en">RowPortlet</base:nls-string>
      </title>
   </portlet-entity>

...
Layout tree

Exactly one is required. Each layout element describes the layout for a page that is opened by a navigation element. There is a one to one correspondence between a page and a layout element. The page layout is determined by row and column containers. Each row or column can contain any number of windows, which in turn contain one portlet each. The layout elements, containers, and windows can be fully defined, including their content, or they can be empty templates to be filled when content is added subsequently. The following element makes up the content of the layout tree.

<layout-element/>

Optional and multiple allowed. The layout element describes the layout of a portal page. Provide one layout element for each page to define in the application. The following attribute is used with this element.

uniqueName

Required. Specifies a unique identifier for the layout element. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

The following elements make up the content of the layout element.

<title/>

Exactly one is required. This element provides a title for the layout element. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content. This title is displayed as the title for the corresponding page.

<simple-container/>

At least one is required. This element defines a row or column in the page layout. This element can be nested.The following attributes are used with this element.

uniqueName

Required. Specifies a unique identifier for the layout element. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

orientation

Required. Specifies how the contents of the container are arranged. The value row arranges content from left to right. The value column arranges content from top to bottom.

The following element makes up the content of this element.

<window/>

Optional and multiple are allowed. A window describes a place in the page layout where portlet content can be inserted. The window can either contain an application artifact or a nested layout. The following attribute is used for the window.

uniqueName

Required. Specifies a unique identifier for the window. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

The following elements make up the content of this element.

<title/>

Optional, no more than one allowed. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content. This string is rendered in the portlet title bar if the title for the <portlet-entity/> is not provided. If neither the portlet entity or the window provide a title, the title is obtained from the portlet.xml (<portlet-name/> element) of the portlet.

<component-definition-ref/>

Optional, but no more than one allowed. This element specifies a reference to the unique name of the component definition for the portlet to be included in this window.

The page layout sample contains six layout elements in its layout tree. This provides six pages showing different ways to arrange the content on the page. The following example shows the first layout element with its simple containers and windows. The inline comments are also shown.
<layout-tree>  
                                          
   
    <layout-element uniqueName="com.ibm.isclite.pagelayout.layoutElement.A">
       <title>
          <base:nls-string lang="en">Two independent Containers</base:nls-string>
       </title>
       <simple-container orientation="row" 
                         uniqueName="com.ibm.isclite.pagelayout.container.A1A">
          <simple-container orientation="row" 
                            uniqueName="com.ibm.isclite.pagelayout.container.A1">
             <window uniqueName="com.ibm.isclite.pagelayout.window.A1">
                <title>
                   <base:nls-string lang="en">Row Portlet</base:nls-string>
                </title> 
                <component-definition-ref>
                   com.ibm.isclite.pagelayout.appElement.A
                </component-definition-ref>
             </window> 
          </simple-container>
          
          <simple-container orientation="column" 
                            uniqueName="com.ibm.isclite.pagelayout.container.A2">
             <window uniqueName="com.ibm.isclite.pagelayout.window.A2">
                <title>
                   <base:nls-string lang="en">Column Portlet</base:nls-string>
                </title>             
            </window> 
        </simple-container>
       </simple-container>
    </layout-element>
Navigation element

Optional, and multiple are allowed. The <navigation-element/> element describes an element or node in the navigation tree. This element can be nested. Navigation elements also require unique names in the installation. Navigation elements are arranged in a tree that reflects the structure of the navigation hierarchy that is created in the portal when the application is deployed. For example, a navigation tree with two primary nodes and two branch nodes each would exhibit the following structure:
<navigation-element>
   <navigation-element/>
   <navigation-element/>
</navigation-element>
<navigation-element>
   <navigation-element/>
   <navigation-element/>
</navigation-element>
In most cases, a navigation element references the layout element of the page that is displayed when the node is selected. The following are the attributes of the <navigation-element/> element.
hidden

Optional. The default is false. When true, this attribute hides the navigation element from the console navigation tree. When this attribute hides a parent navigation element, it also hides any children. IBM recommends that you associate a parentTreeRef attribute containing an empty string with each hidden navigation element. If you are planning to launch a navigation node, the navigation node must point to a layout element. In other words the navigation element must contain the layoutElementRef attribute.

uniqueName
Required. Specifies a unique identifier for the navigation element. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.You can also use this attribute to associate a navigation element from another product with WAS. In this case, omit the title element from the navigation element. For example, if Product A has a navigation element titled "Setting the background color" that also works with Product B, then Product B would include a navigation element without a title that specifies the same unique name as this node from Product A. In addition, you can specify a wild card pattern to include multiple navigation elements from another products. The wild card is specified using two dashes (--). For example, the following pattern would include all of the navigation elements from a product that is already deployed and that have a unique name starting with com.ibm.
<navigation-element uniqueName=”com.ibm.--”>
</navigation-element>
layoutElementRef

Optional. Page to be displayed when the node is selected.
The following elements make up the content of the navigation element.
<title/>

Optional, no more than one allowed. This element provides a title for the node to be displayed in the navigation. This title is also displayed in the task tree for My Tasks, and in the View selection menu over the navigation . Because of the limited viewable width of the View selection menu, try to keep the character length of the title to a minimum. To provide a localized string, use the <base:nls-string/> or <base:nls-ref/> elements for the title content.

<parent-tree/>
Optional, no more than one allowed. Parent node and position under the parent node where the current navigation element is to be located. The parent node need not be part of the current application definition. If a requested parent node does not exist, the node is appended to the bottom of the navigation tree and is merged into the parent when the parent application is deployed.The following attributes are used with this element.

parentTreeRef

Required. Indicates the unique name of the navigation element under which this node should be placed.

ordinal

Optional. Provides a non negative integer to determine the relative order of nodes under a particular parent tree. If no ordinal is specified, or if two navigation elements specify the same ordinal for a navigation level, the node is located in the order in which it is deployed.

The following example from the tree merge sample shows how the <parent-tree/> element is used to merge the navigation elements into the navigation for the page layout sample. The parentTreeRef attribute specifies the unique name of the top level navigation element for the page layout sample. Child navigation elements are placed under the corresponding top level node for tree merge. Ordinal is not specified, so this navigation tree is appended to the page layout navigation tree.
<navigation-element uniqueName="com.ibm.isclite.samples.navigationElement.TreeMerge">

   ...
   <parent-tree parentTreeRef="com.ibm.isclite.samples.navigationElement.Topology"/>

   <navigation-element uniqueName="com.ibm.isclite.treemerge.navigationElement.A" 
                       layoutElementRef="com.ibm.isclite.TreeMerge.layoutElement.A">
   ...
   </navigation-element>

   <navigation-element uniqueName="com.ibm.isclite.treemerge.navigationElement.B" 
                       layoutElementRef="com.ibm.isclite.TreeMerge.layoutElement.B">

   ...
   </navigation-element>

</navigation-element>
<navigation-content/>
Optional, multiple allowed. This element defines the content of a window in a page layout. This can be used to supply the content for a window at runtime or to map different portlets to the same window, depending on which navigation element is selected. The following attributes are used with this element.

uniqueName

Required. Specifies a unique identifier for the navigation content. To guarantee uniqueness, see Console module elements - guidelines for unique identifiers.

componentDefinitionRef

Required. Indicates the unique name of the component definition that should be rendered in the window. The component definition can be a portlet entity or a url link. If the component definition specifies a url-link, omit the windowRef attribute. Windows cannot render external URLs.

windowRef

Optional. Indicates the unique name of the window where the component definition should be rendered. If this attribute is not specified, the component definition applies to the entire layout element. Multiple <navigation-content/> elements can specify the same window. Optional.

The following example from the page layout sample illustrates how the <navigation-content/> element can be used.
A portlet is defined in a component definition with the unique name com.ibm.isclite.pagelayout.appElement.B .
<portlet-entity uniqueName="com.ibm.isclite.pagelayout.appElement.B" 
                portletDefinitionRef="com.ibm.isclite.pagelayout.appElementDefinition.B">
   <title>
      <base:nls-string lang="en">ColumnPortlet</base:nls-string>
   </title>
</portlet-entity>
A window is defined without a component definition reference, which means it has empty content.
<simple-container orientation="column" 
                  uniqueName="com.ibm.isclite.pagelayout.container.A2">
   <window uniqueName="com.ibm.isclite.pagelayout.window.A2">
      <title>
         <base:nls-string lang="en">Column Portlet</base:nls-string>
      </title>             
   </window> 
</simple-container>
The navigation content specifies the unique name of the portlet and window for the componentDefinitionRef and windowRef attributes respectively.

<navigation-element uniqueName="com.ibm.isclite.pagelayout.navigationElement.pagelayoutA" 
                    layoutElementRef="com.ibm.isclite.pagelayout.layoutElement.A">
   <title>
      <base:nls-string lang="en">2 Separate Containers</base:nls-string>
   </title>
   <navigation-content uniqueName="com.ibm.isclite.pagelayout.navigationContent.A2" 
                       componentDefinitionRef="com.ibm.isclite.pagelayout.appElement.B" 
                       windowRef="com.ibm.isclite.pagelayout.window.A2"/>
</navigation-element>
<preference/>
Optional. Indicates the unique name of the application definition for a product. This is used to include the node in the navigation tree of the product when console users select the product title to filter the navigation. For example:
The page layout sample is deployed with the title Integrated Solutions Console Sample (as defined by the title tag for the application definition). This title is added to the product filter of the navigation View selection list.
The tree merge sample is subsequently deployed specifying page layout as a prerequisite application. To ensure that navigation nodes for tree merge are also displayed when the console user selects Integrated Solutions Console Sample for product filtering, the navigation elements includes this preference definition.
<preference name="ProductFilter">
   <base:value>
      <base:string>com.ibm.isclite.samples.PageLayout</base:string>
   </base:value>
</preference>
The name attribute must be set to ProductFilter. The <base:string/> element must indicate the unique name of the application definition for the prerequisite product.
Reference topic