
	Portal Guide

CHAPTER 3 Working with Portal Layouts

This chapter explains how to use portal layouts to control the appearance of user personalization and group pages. It contains the following sections:

About portal layouts

A portal layout is a template that defines how a set of selected portal components should appear on a page. Each user personalization page or group page in a Director portal application uses a portal layout to specify how the selected components should be arranged on the page. Director keeps the user's selected components separate from the portal layout, so that a layout can easily be applied to a group of selected components.

Predefined layouts Director ships with several predefined layouts:

Layout	Description	Preview
1column	Creates a single column. This layout is used primarily for wireless applications.
2column	Creates two columns of equal size.
3column	Creates three columns of equal size.
ClassicPortalLayout	Used to migrate existing portal applications.
HeaderContent	Creates a header area and a content area.
HeaderNavContent	Creates a header area, a navigation bar, and a content area.
HeaderNavContentFooter	Creates a header area, a navigation bar, a content area, and a footer area.
MyNovell	Creates an XHTML layout.

Custom layouts You can also create your own custom layouts, using the Portal Layout and Portal Layout Definition Wizards in Workbench.

For more information For details on using the Portal Layout and Portal Layout Definition Wizards, see Creating Custom Layouts.

A portal layout consists of these files:

File(s)	Description
Layout descriptor file	Describes the layout. This XML file provides a display name, description, and preview image file for the layout. The layout descriptor file also includes a reference to the layout definition file as well as an element that indicates whether the format for the layout definition file is XML or XHTML. Each layout used by a portal application must have a separate layout descriptor file. The layout descriptor file can have any name you like.
Layout definition file	Describes the layout in XML or XHTML format. This file defines the sections within the layout, as well as the width of the main page and the width of each section. The layout definition also specifies how components within a particular section will flow (left to right or top to bottom). Each layout used by a portal application must have a separate layout definition file. The layout definition file typically has the same name as the descriptor file, with Def (for definition) appended. For example, if the descriptor file is called HeaderContent.xml, the layout definition file might be called HeaderContentDef.xml. This naming convention is recommended, but not required.
Supporting graphics files	Define preview images for the layout.

File(s)

Description

Layout descriptor file

Describes the layout. This XML file provides a display name, description, and preview image file for the layout. The layout descriptor file also includes a reference to the layout definition file as well as an element that indicates whether the format for the layout definition file is XML or XHTML.

Each layout used by a portal application must have a separate layout descriptor file. The layout descriptor file can have any name you like.

Layout definition file

Describes the layout in XML or XHTML format. This file defines the sections within the layout, as well as the width of the main page and the width of each section. The layout definition also specifies how components within a particular section will flow (left to right or top to bottom).

Each layout used by a portal application must have a separate layout definition file. The layout definition file typically has the same name as the descriptor file, with Def (for definition) appended. For example, if the descriptor file is called HeaderContent.xml, the layout definition file might be called HeaderContentDef.xml. This naming convention is recommended, but not required.

Supporting graphics files

Define preview images for the layout.

Associated files All of the files associated with a portal layout must be stored in the portal-layout directory within a resource set. The ID for a layout is the name of its descriptor file, without the XML extension.

For more information about where files are located in a resource set, see the section on Subdirectories for resources and Java classes in the Core Development Guide.

Layout descriptor file

The layout descriptor file provides a display name, description and preview image file for the layout. The layout descriptor file can have any name you like. Each layout used by a portal application must have a separate layout descriptor file.

These are the elements in the layout descriptor file:

Element name	Description
portal-layout	The root node of a portal layout
display-name	The name used to identify the layout in the user interface of a portal application.
description	The description of the layout.
preview-image	A small image showing what the layout might look like. The path to this image could be a fully qualified URL or an URL that contains portal replacement strings. For more information on portal replacement strings, see Portal Replacement Strings.
layout-definition-file	The name of the layout definition file. This file contains the actual layout.
layout-definition-format	The format of the layout. A layout definition can use either of the following formats: text/xml (for XML) text/xhtml (for XHTML) HTML is not a supported layout definition format.

Here is an example of a layout descriptor file for a layout called HeaderContent. The layout descriptor file is called HeaderContent.xml:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE portal-layout PUBLIC "-//SilverStream Software, LLC//DTD Portal Layout 4.0//EN" "portal-layout_4_0.dtd">
  <portal-layout>
    <display-name>Header Content</display-name>
    <description>Header and content sections</description>
    <preview-image>$RESOURCE_URL$/portal-layout/images/HeaderContent.gif
      </preview-image>
    <layout-definition-file>HeaderContentDef.xml</layout-definition-file>
    <layout-definition-format>text/xml</layout-definition-format>
  </portal-layout>

The string $RESOURCE_URL$ shown above is an example of a portal replacement string. Replacement strings allow you to include runtime, context-based information in a portal application. Replacement strings are keywords that reference things that can change dynamically at runtime, such as a user's current theme or the currently rendered component ID. When these keywords are detected at runtime, they are replaced based on information from the current HTTP request or the current portal context.

For more information about portal replacement strings, see Portal Replacement Strings.

Layout definition file

The layout definition file for a portal layout describes the sections within the layout, as well as the width of the main page and the width of each section. The layout definition also specifies how components within a particular section will flow (left to right or top to bottom).

A layout definition can use either of the following formats:

text/xml (for XML)
text/xhtml (for XHTML)

HTML is not a supported layout definition format.

You specify the format you plan to use in the <layout-definition-format> element of the layout descriptor file.

XML format

If you use XML to specify the layout definition, you must use the following elements to define the layout:

Element name	Description
portal-layout-def	The root node of a portal layout definition
section-container	An area within the layout that can contain one or more sections. When a section-container is of type row, the generated HTML for the element is a table row (<tr>). When a section-container is of type column, the generated HTML for the element is a table cell (<td>).
s3-section	A section within a section-container. Each s3-section can display one or more portal components. Each s3-section specifies a flow attribute, which indicates whether components within the section should flow from top to bottom (vertical flow) or from left to right (horizontal flow). In addition, each s3-section can specify width and style settings. To identify each s3-section, you also need to specify an id for the section.

Element name

Description

portal-layout-def

The root node of a portal layout definition

section-container

An area within the layout that can contain one or more sections. When a section-container is of type row, the generated HTML for the element is a table row (<tr>).

When a section-container is of type column, the generated HTML for the element is a table cell (<td>).

s3-section

A section within a section-container. Each s3-section can display one or more portal components. Each s3-section specifies a flow attribute, which indicates whether components within the section should flow from top to bottom (vertical flow) or from left to right (horizontal flow). In addition, each s3-section can specify width and style settings.

To identify each s3-section, you also need to specify an id for the section.

Here is an example of an XML layout definition file for a layout called HeaderContent. The layout definition file is called HeaderContentDef.xml:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE portal-layout-def PUBLIC "-//SilverStream Software, LLC//DTD Portal Layout Def 4.0//EN" "portal-layout-def_4_0.dtd">
  <portal-layout-def>
    <section-container type="row">
      <s3-section flow="vertical" id="1" 
       style="padding-bottom:5px;padding-right:5px"/>
    </section-container>
    <section-container type="row">
      <s3-section flow="vertical" id="2" 
       style="padding-bottom:5px;padding-right:5px"/>
    </section-container>
  </portal-layout-def>

For more information To see how each element in a portal layout is translated into HTML, see PortalLayout.xsl in the portal-style folder within the portal_core_resource.jar file (this file is available in the WEB-INF\lib directory of the WAR file for your Web application).

XHTML format

If you specify the layout definition in XHTML, you have much more control over the layout than you would with XML. XHTML layouts can be used for both user pages and group pages, although they are particularly useful for group pages. For example, you might use an XHTML layout to brand a Web site with a particular corporate look. If you define the branding in a group page, each user page displayed within this group page will have the branding.

When you use the XHTML format, you must ensure that the document is formed in compliance with XHTML guidelines. Here are some guidelines you should follow to ensure that your document is well-formed:

Each tag you specify must have a corresponding end tag
The case for the begin and end tags must match
Attribute values must be enclosed in quotes

For more information about XHMTL, see the W3C Web site.

To reserve space for users to place their selected components, you need to place <s3-section> tags throughout the XHTML document.

The XHTML document should not contain the HTML, HEAD, and BODY tags. These are added automatically by the Presentation Manager.

Here is an example of an XHTML layout definition file for a layout called MyNovell. The layout definition file is called MyNovell.html:

  <table border="0" width="100%" bgcolor="#336699">
   <tr>
    <td>
  
     <table border="0" width="100%">
      <tr>
       <td width="300">
        <img src="../../resource/
          portal-layout/images/mynovell_logo.jpg"/>
       </td>
       <td width="65">
         <a href="../comp/PortalPersonalizer">
         <img border="0" src="../../resource/
          portal-layout/images/mynovell_personalize.gif"/>
         </a>
       </td>
       <td width="65">
         <a href="../myportal">
          <img border="0" src="../../resource/
           portal-layout/images/mynovell_myportal.gif"/>
         </a>
       </td>
       <td></td>
      </tr>
     </table>
  
    </td>
   </tr>
   <tr>
    <td>
  
     <table border="0" height="500" cellpadding="0" 
       cellspacing="0" width="100%"> 
      <tr>
       <td rowspan="3" width="190">
  
        <table width="100%" height="95%" border="0">
         <tr>
          <td valign="top">
  <!-- Here is section 1 where portal components will go at runtime -->
           <s3-section id="1"/>
          </td>
         </tr>
        </table>
  
         </td>
         <td width="65" valign="bottom"
          style="background:url
           (../../resource/portal-layout/images/mynovell_topleft.gif) 
             no-repeat top left;"></td>
         <td height="42" style="background:url
          (../../resource/portal-layout/images/mynovell_top.gif) 
            top left;"></td>
         <td width="61" height="42" valign="bottom"
           style="background:url
           (../../resource/portal-layout/images/mynovell_topright.gif) 
             no-repeat top right;"></td>
        </tr>
        <tr>
         <td style="background:url(../../resource/portal-layout/images/mynovell_left.gif) 
          repeat-y top left;"></td>
         <td bgcolor="white" valign="top">
  <!-- Here is section 2 where portal components will go at runtime -->
           <s3-section id="2"/>
        </td>
        <td style="background:url(../../resource/
          portal-layout/images/mynovell_right.gif) 
           repeat-y top right;"></td>
        </tr>
       <tr>
        <td width="65" height="66" valign="top"
         style="background:url(../../resource/
          portal-layout/images/mynovell_bottomleft.gif) 
           no-repeat top left;"></td>
        <td style="background:url(../../resource/
          portal-layout/images/mynovell_bottom.gif) 
           repeat-x bottom left;"></td>
        <td width="61" height="66" valign="top"
         style="background:url(../../resource/
           portal-layout/images/mynovell_bottomright.gif) 
            no-repeat top right;"></td>
       </tr>
     </table>
  
    </td>
   </tr>
  </table>

Working with user pages

To define a new personal page, a portal user needs to use the Portal Personalizer to specify the page contents as well as the layout for the page. The Component Selector allows the user to specify which components should appear on the page. The Layout Selector provides a user interface for selecting the layout.

For more information For complete details on using the Portal Personalizer to create user pages, see Working with user pages.

User pages are not tightly bound to layouts. That means users can switch layouts for their pages without disrupting the page contents. When the user applies a new layout to a page, any previously selected components are automatically displayed using the new layout.

Here's a sample user page:

  <?xml version="1.0" encoding="UTF-8"?>
  <portal-user-page>
   <layout-id>2column</layout-id>
   <display-name>asdf</display-name>
   <description>asdf</description>
   <selected-components>
    <s3-section id="1">
     <s3-component id="PhoneList"
       instance="c373e9ed6906a4798f6a0010a4aa42ee"/>
    </s3-section>
    <s3-section id="2">
     <s3-component id="RSSViewer"
       instance="c373e9ed83416f668f6a0010a4aa42ee"/>
    </s3-section>
   </selected-components>
  </portal-user-page>

User pages are stored in the PROFILEUSERPREFERENCES table. The XML definition for each user page is stored in the PREFDATA column.

Working with group pages

Group pages are defined in the same manner as user pages, except that they must be defined by a group page administrator. To define a new group page, an administrator uses the Portal Personalizer to specify the page contents and the layout. The administrator uses the Component Selector to specify which components should appear on the page and the Layout Selector to select the layout.

For more information For complete details on using the Portal Personalizer to create group pages, see Working with group pages.

Like user pages, group pages are not tightly bound to layouts. That means administrators can switch layouts for their pages without disrupting the page contents. When the user applies a new layout to a page, any previously selected components are automatically displayed using the new layout.

Here's a sample group page:

  <portal-group-page>  
   <layout-id>HeaderContent</layout-id>  
   <display-name>SampleGroupPage</display-name>  
   <selected-components>
    <s3-section id="1">
      <s3-component id="MyPages"
        instance="425f0a827a2e11d4910f0010a4e7ad7f"/>
    </s3-section>
    <s3-section id="2">
      <s3-component id="PortalUserPage"
        instance="1426bv67f760f9a85f928633786925f1"/>
      </s3-section>
   </selected-components>
  </portal-group-page>

Group pages are stored in the PROFILEGROUPPREFERENCES table. The XML definition for each group page is stored in the PREFDATA column.

Working with the layout API

The Director API provides two interfaces for working with layouts:

EbiLayoutManager
EbiLayoutInfo

EbiLayoutManager provides methods for accessing EbiLayoutInfo objects. EbiLayoutInfo provides methods for retrieving various kinds of information about a layout, including its display name and description. The EbiLayoutInfo interface also provides access to the URIs for a layout's preview and thumbnail images.

To access an EbiLayoutManager object, you need to use the getLayoutManager() method on the EboFactory class for the Portal subsystem.


	Portal Guide