The following descriptors are required for the console module.
- Web application descriptor (web.xml). This descriptor
is required and described by the Java Servlet Specification.
- Portlet application descriptor (portlet.xml). This
descriptor is required and described by the Java Portlet Specification. Refer
to the console module samples for examples of how to create the portlet.xml.
- Portal topology descriptor (ibm-portal-topology.xml).
This descriptor is unique to console modules and defines the portlets and
resources in the module, how it is laid out on the page, and how it is accessed
from the navigation.
- Portal security descriptor (ibm-portal-security.xml).
This descriptor is unique to console modules and defines roles and access
to navigation nodes and portlets.
The topology and security descriptors are the main component of PAA packages
that distinguish them from other portal application WAR files. The console
module samples include these descriptors and demonstrate their features. The
sample descriptors provide inline comments that explain the elements and how
they are used.
For your first console module, you should use the PAA Visual Designer plugin
to the Application Server Toolkit to develop the descriptors. If you prefer
to create them manually to become familiar with the structure of the XML,
the steps in this topic show how to create simple descriptors that can be
used to deploy an application into the samples provided by IBM. After following
these steps, you should refer to the samples and the reference topics for
the PAA schemas for more complete information.
Portal topology descriptor
To follow these steps,
open a file with the name ibm-portal-topology.xml in
a text or XML editor and save each change at the end of each step.
- Copy the following elements into ibm-portal-topology.xml.
<?xml version="1.0" encoding="UTF-8"?>
<ibm-portal-topology
xmlns="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-topology.xsd"
xmlns:base="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-base.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-topology.xsd ibm-portal-topology.xsd">
<application-definition appID="com.ibm.isclite.samples.basicModule" version="6.1">
</application-definition>
<PAA-ref>com.ibm.isclite.samples.PageLayout</PAA-ref>
</ibm-portal-topology>
- Create a title for your application. The title is the first element in
the application definition element.
<title>
<base:nls-string lang="en">My basic module</base:nls-string>
</title>
- Place the component tree after the <requires/> element as shown.
<component-tree uniqueName="com.ibm.isclite.samples.basicModule.appTree">
<portlet-definition uniqueName="com.ibm.isclite.samples.basicModule.portletDefinition.A">
<title>
<base:nls-string lang="en">My basic module</base:nls-string>
</title>
<resource-link name="basicModule"
portletApplication="com.ibm.isclite.samples.basicmodule.BasicModule.01a"
type="static"/>
</portlet-definition>
<portlet-entity uniqueName="com.ibm.isclite.samples.basicModule.portletEntity.A"
portletDefinitionRef="com.ibm.isclite.samples.basicModule.portletDefinition.A">
<title>
<base:nls-string lang="en">My basic module</base:nls-string>
</title>
</portlet-entity>
</component-tree>
- The name attribute of the <resource-link/> element
must specify the <portlet-name/> from the portlet deployment descriptor.
- The portletApplication attribute of the <resource-link/>
element must specify the id attribute of the <portlet-app/>
element from the portlet deployment descriptor.
- The portletDefinitionRef attribute of the <portlet-entity/>
element references the unique name of the <portlet-definition/>. Subsequent
elements in this descriptor use the unique name of the <portlet-entity/>
to invoke the portlet. Multiple portlet entities can point to the same portlet
definition. For the purpose of this exercise, a single portlet definition
is provided with a single portlet entity.
- The portlet title that is rendered in this example is derived from the
title in the portlet entity. If that value is not provided, the portlet title
is rendered by the title provided by the <window/> element in the layout
tree. If that value is also not provided, the title is obtained from the <portlet-name/>
element in the portlet.xml for the portlet indicated by the <resource-link/>.
- Place the layout tree after the component tree as shown.
<layout-tree>
<layout-element uniqueName="com.ibm.isclite.samples.basicModule.layoutElement.A">
<title>
<base:nls-string lang="en">My basic module</base:nls-string>
</title>
<simple-container orientation="row"
uniqueName="com.ibm.isclite.samples.basicModule.container.A">
<window uniqueName="com.ibm.isclite.samples.basicModule.window.A">
<title>
<base:nls-string lang="en">My basic module</base:nls-string>
</title>
<component-definition-ref>
com.ibm.isclite.samples.basicModule.portletEntity.A
</component-definition-ref>
</window>
</simple-container>
</layout-element>
</layout-tree>
- Each layout element in the layout tree defines the layout of a page in
the console.
- Each page can have nested containers, and each simple container can have
multiple windows. Each simple container has either a row or column orientation.
The nesting of these containers can create a complex table structure for the
page layout.
- The <component-definition-ref/> element specifies the unique name of
the portlet entity that provides the content of this window.
- Create the navigation element after the layout tree as shown.
<navigation-element uniqueName="com.ibm.isclite.samples.navigationElement.basicModule"
layoutElementRef="com.ibm.isclite.samples.basicModule.layoutElement.A">
<title>
<base:nls-string lang="en">Basic Module Sample</base:nls-string>
</title>
<preference name="ProductFilter">
<base:value>
<base:string>com.ibm.isclite.samples.PageLayout</base:string>
</base:value>
</preference>
<parent-tree parentTreeRef="com.ibm.isclite.samples.navigationElement.Samples"/>
</navigation-element>
- Each navigation element defines a node in the console navigation. If you
nest the navigation elements, it creates a hierarchical tree structure that
is reflected in the console navigation. For the purpose of this exercise,
only a single navigation element is provided. The layoutElementRef attribute
indicates the unique name of the layout element that is rendered on the page
that is displayed when this element is selected by the console user.
- The content of the ProductFilter preference indicates
the appID of the lead application. This is used to render
this navigation element when the lead product is selected by the console user
for filtering the navigation.
- The content of the parentTreeRef element indicates
the unique name of the parent navigation element for this element.
The following figure shows how this navigation element is rendered
with the page layout sample. In this figure, the user has selected
Integrated
Solutions Console Sample from the
View selection
list to filter the navigation.
Figure 1. Sample console module
navigation
When you have finished, save and close the file and store in the /WEB-INF directory
of your console module project.
Sample portal security descriptor
To follow these
steps, open a file with the name ibm-portal-security.xml in
a text or XML editor and save each change at the end of each step.
- Copy the following elements into ibm-portal-security.xml.
<?xml version="1.0" encoding="UTF-8"?>
<ibm-portal-security
xmlns="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-security.xsd"
xmlns:base="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-base.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-topology.xsd ibm-portal-topology.xsd
http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-base.xsd ibm-portal-base.xsd
http://www.ibm.com/websphere/appserver/schemas/6.0/ibm-portal-security.xsd ibm-portal-security.xsd">
</ibm-portal-security>
- Add the <application-role/> element as the content of the <ibm-portal-security/>
element.
<application-role uniqueName="monitor">
</application-role>
This sample identifies the administrative role, monitor,
for access rights. See Example: Portal security schema for a
complete description of this element and the uniqueName attribute.
- Add the following <portal-role/> elements as the content of the application
role.
<portal-role object-ref="com.ibm.isclite.samples.navigationElement.basicModule"/>
<portal-role object-ref="com.ibm.isclite.samples.basicModule.navigationElement.A"/>
<portal-role object-ref="com.ibm.isclite.samples.basicModule.portletEntity.A"
role-type="Privileged User"/>
This sample assigns permission to a user with monitor access
to view two navigation elements and to view, edit, and access help for one
portlet. See Example: Portal security schema for a complete
description of this element and its attributes.
When you have finished, save and close the file and store in the /WEB-INF directory
of your console module project.