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. Specifies the 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 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 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">
<!-- PageLayoutPortlet 1-->
<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 that you want to
define in the application.
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 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>
<!--PageLayout A contains Two Seperate Containers:
The first Container has row orientation with one window inside the container
The second Container has column orientation with one window inside the container
This layout uses is-spot to specify the application for the window.
Therefore you must specify the navigation-content in the navigation element
below that uses this layout element.
-->
<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. It is recommended 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 this product. In this case, you must 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. Specifies the 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. Specifies the 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.
<!--This Navigation Element is for Layout A -->
<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>
Note: 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.