Working with PID Pages

This chapter describes basic techniques for writing PID pages. It includes these topics:

About PID pages

A portal application can contain Portal Page ID (PID) pages. PID pages are pages that include s3-component tags. PID pages can contain HTML or XML.

Where to put your PID pages PID pages must be packaged in a resource set WAR, along with other resources required for the application. The PID pages must be located in the portal-page directory within the resource set.

PID page descriptors Each PID page must have at least one XML descriptor. Each descriptor specifies the name of the HTML or XML file that provides content for the page, as well as additional parameters that control how the page will look and behave at runtime. The XML descriptor for a PID page must also be located in the portal-page directory within the resource set.

Here is an example of a descriptor for a portal page that provides HTML content. It specifies the name of the HTML file that provides content, as well as a display name and a description:

  <portal-page>
   <display-name>Hello World</display-name>
   <description>Hello World Page</description>
   <file-name>HelloWorld.html</file-name>
  </portal-page>

Here is an example of a descriptor for a portal page that provides XML content. It specifies the name of the XML file as well as the name of a portal style that defines the XSL file that will be used for translation. This descriptor also specifies security role mappings for the page:

  <portal-page>
   <display-name>Hello World</display-name>
   <description>Hello World Page</description>
   <category>UserPages</description>
   <mime-type>text/xml</mime-type>
   <style-name>HelloWorld</style-name>
   <file-name>HelloWorld.xml</file-name>
   <run-role-map>
    <role-name>manager</role-name>
    <role-name>administrator</role-name>
   </run-role-map>
  </portal-page>

The descriptor file for a portal page must have an XML extension. To indicate which portal page a descriptor applies to, you may want to include the file name of the portal page in the name of the descriptor. For example, if the portal page is stored in a file called HelloWorld.html, you might name the descriptor file HelloWorld.html.xml.

URLs for PID pages To display PID pages, the portal's base servlet breaks the request URL down into several components:

The portal pages path specifies the path to portal pages in the WAR. This portion of the URL is controlled by the PortalPathPagesKey context parameter in the web.xml for the WAR:
```
  <context-param>
   <param-name>PortalPathPagesKey</param-name>
   <param-value>pages</param-value>
   <description />
  </context-param>
```
The PID page name identifies the requested item in the WAR. The PID page name specifies the name of the XML descriptor (without the XML extension). By convention, the name of the XML descriptor is often the same as the name of the portal page file. However, it need not be.

For example, suppose you want to access a portal page that has a descriptor file called HelloWorld.html.xml. The page is deployed to the Express Portal. In this case, you could use the following URL to display the page:

  http://localhost/ExpressPortal/portal/pages/HelloWorld.html

Building PID pages that contain HTML

You can develop portal pages as typical HTML pages with graphics, tables, forms, and style sheets. You can use the text editor provided with development environment, or any other HTML editor.

To write the HTML, you need to know how to include portlets and portal components on the page.

Portlet tag

When you want to use a portlet in a PID page, you specify a special tag recognized by exteNd Director. You put the tag in the HTML where you want the portlet to insert its content.

The format for a portlet tag is:

  <s3-component id="portletID/componentID" instance="instanceID" />

where arguments are as follows:

Argument	Description
portletID/componentID	The ID given to the portlet or component. For portlets, the ID is the portlet registration ID. For components, the ID is the name given to the XML file (without the extension) that describes the component. For example, if the name of the XML file for a component is MyComponent.xml, the component name is MyComponent.
instanceID	A name used to identify the portlet or component on the page. This name uniquely identifies this instance of the portlet or component. A good practice is to prefix the instance ID with the name of the page that the portlet or component is assigned to.

Argument

Description

portletID/componentID

The ID given to the portlet or component.

For portlets, the ID is the portlet registration ID.

For components, the ID is the name given to the XML file (without the extension) that describes the component. For example, if the name of the XML file for a component is MyComponent.xml, the component name is MyComponent.

instanceID

A name used to identify the portlet or component on the page. This name uniquely identifies this instance of the portlet or component.

A good practice is to prefix the instance ID with the name of the page that the portlet or component is assigned to.

For example, to put a portlet in a table cell on your page, you would write HTML like this:

  <td height="200"> 
     <s3-component 
       id="PhoneList"
       instance="CorpHome_MyPhoneList" />
  </td>

You can also specify custom parameters that alter the behavior of the portlet or component. A custom parameter is an arbitrary pairing of a name and a value:

  <td height="200"> 
     <s3-component
       id="MyPortlet"
       instance="CorpHome_myportlet" MYATTRIBUTE="myvalue" />
  </td>

The code that implements the component must check for the value of the parameter (in this case MYATTRIBUTE) and modify its behavior accordingly.

Building PID pages that contain XML

XML is a practical way to render text-based pages with a simple layout. It is particularly useful when the page is made up of portlets or components.

You determine the XML elements you want to represent on your page. You also define an XSL style sheet for rendering the elements into HTML. The base servlet combines the two to display the portal page in the client browser.

You can use the same XSL for some or all of your PID pages to give your portal a consistent appearance. It's easy to tweak the appearance by changing the XSL, which affects all pages that use it, or by providing another XSL specification for any or all of the pages.