Portal Guide

CHAPTER 4

Working with Portal Layouts

This chapter explains how to use portal layouts to control the appearance of personal, shared, and container pages. It contains the following sections:

About portal layouts

A portal layout is a template that defines how a set of selected portlets should appear on a page. Each personal, shared, and container page in an exteNd Director portal application uses a portal layout to specify how the selected portlets should be arranged on the page. exteNd Director keeps the user's selected portlets separate from the portal layout, so that a page's layout can be changed without affecting the selected portlets.

Predefined layouts

exteNd Director ships with several predefined layouts. The following layouts are available to all users:

Layout	Description	Preview
1 Column	Creates a single column. The portlet flow is top to bottom.
2 Columns	Creates two columns of equal size. The portlet flow is top to bottom within the columns.
2 Columns 30/70	Creates two columns of proportional size. The first column occupies 30% of the page width and the second column occupies 70% of the page width.
3 Columns	Creates three columns of equal size. The portlet flow is top to bottom within the columns.
Classic Portal Layout	Creates a header area, three columns, and a footer area.
Header Content	Creates a header area and a content area.
Header Nav Content	Creates a header area, a navigation bar, and a content area.
Header Nav Content Footer	Creates a header area, a navigation bar, a content area, and a footer area.

The following layouts are available only to layout administrators:

Layout	Description	Preview
My Novell Layout	Creates a sample XHTML layout.

Creating your own layouts

You can also create your own layouts. To do this, you use the Portal Layout and Portal Layout Definition Wizards in exteNd Director, as described in Creating Custom Layouts.

Files associated with portal layouts

Each layout in a portal application must provide each of the following files:

File(s)	Description
Layout descriptor file	Describes the layout. This XML file specifies the following information: Display name Description Preview image file Reference to the layout definition file Layout definition format (XML or XHTML) You can give the layout descriptor file any name you like.
Layout definition file	Specifies the physical characteristics of the layout in XML or XHTML format. This file provides the following information: Sections within the layout Width of the main page Width of each section How portlets should flow within a particular section (left to right or top to bottom). 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 specifies the following information:

Display name
Description
Preview image file
Reference to the layout definition file
Layout definition format (XML or XHTML)

You can give the layout descriptor file any name you like.

Layout definition file

Specifies the physical characteristics of the layout in XML or XHTML format. This file provides the following information:

Sections within the layout
Width of the main page
Width of each section
How portlets should flow within a particular section (left to right or top to bottom).

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.

The layout descriptor and layout definition files must be stored in the portal-layout directory within a resource set.

The internal identifier 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 Developing exteNd Director Applications.

Layout descriptor file

Each layout used by a portal application must have a layout descriptor file. You can give the layout descriptor file any name you like. The layout descriptor file specifies the following information for the layout:

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 path to 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.
run-role-map	The set of roles that can run a portal page with this layout. If you do not specify a run-role-map, all users can run portal pages with this layout. IMPORTANT: If you specify a run-role-map for a layout, you should specify the equivalent list-role-map.
list-role-map	The set of roles that can view this layout from a selection list. If you do not specify a list-role-map, all users can view this layout.

Here is an example of a layout descriptor file for a layout called Header Content. 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 5.0//EN" "portal-layout_5_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 portlet 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 portlets should flow within a particular section (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 portlets. S3-sections are used at runtime to allow users to select the portlets they want in those sections. Each s3-section specifies: A flow attribute, which indicates whether portlets within the section should flow from top to bottom (vertical flow) or from left to right (horizontal flow). The width and style settings. An identifier for the section.
s3-component	Allow you to place content anywhere in your XHTML layout.

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;" width="100%"/>
  </section-container>
  <section-container type="row">
  <s3-section flow="vertical" id="2" style="padding-bottom:5px;" width="100%"/>
  </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 of the resource set in 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 personal, shared, and container 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 container page, each personal page displayed within this container page will have the branding.

When you use the XHTML format, the markup is well-formed. 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

To reserve space for users to place their selected portlets, you need to place <s3-section> tags throughout the XHTML document. XHTML layouts can use scoped paths to dynamically point to portal resources. For example, the following scoped path shows how to access an image in the resource set.

  <img src="${Portal/Uri/Context/resource/   portal-layout/images/mynovell_logo.jpg}"/>

The XHMTL layout can only contain HTML, HEAD, and BODY tags when it is used as a portal container page.

Here is an example of an XHTML layout definition file for a layout called MyNovell. (It is a portal container page.) The layout definition file is called MyNovell.html:

  <html>
  <head>
  <title>MyNovell.com</title>
  <s3-component id="ThemeTester" mode="link-only"/>
  <script language="JavaScript" type="text/JavaScript">
   onLoadFct = [];
   function compareOnLoadPriority(a, b) {
    if (a != undefined &amp;&amp; b != undefined) { 
     if ( a.priority &lt; b.priority ) return -1
     if ( a.priority &gt; b.priority ) return 1
    }
    return 0
   }
  function runOnLoad() {
    var lg = onLoadFct.length;
    if (lg &gt; 0) {
     if (lg &gt; 1) onLoadFct.sort(compareOnLoadPriority);
     var i = 0;
     while(i &lt; lg) {
      if (onLoadFct[i] != undefined) {
       (eval(onLoadFct[i].fct))();
      }
      i++;
     }
    }
   }
  function setOnLoad(priority,fct) {
    var pos = onLoadFct.length;
    onLoadFct[onLoadFct.length] = {}
    onLoadFct[pos].priority = priority;
    onLoadFct[pos].fct = fct;
   }
  </script>
  </head>
  <body margintop="0" bgcolor="#336699" marginleft="0" onLoad="runOnLoad()">
  <table border="0" width="100%" bgcolor="#336699">
    <tr>
      <td>
  <table border="0" width="100%">
          <tr>
            <td width="300"><img src="${Portal/Uri/Context/resource/portal-layout/images/mynovell_logo.jpg}"/></td>
            <td width="65"><a href="../../portlet/Personalize"><img border="0" src="${Portal/Uri/Context/resource/portal-layout/images/mynovell_personalize.gif}"/></a></td>
            <td width="65"><a href=""><img border="0" src="${Portal/Uri/Context/resource/portal-layout/images/mynovell_myportal.gif}"/></a></td>
            <td></td>
          </tr>
        </table>
  </td>
    </tr>
    <tr>
      <td>
        
  	 <s3-component id="PhoneList" instance="page_phome"/>
  	 <table border="0" height="500" cellpadding="0" cellspacing="0" width="100%"> 
          <tr>
            <td rowspan="3" width="165">
              <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" style="padding-bottom:5px;"/>
                  </td>
                </tr>
              </table>          
            </td>
            <td width="65" valign="bottom" style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_topleft.gif}) no-repeat top left;"></td>
            <td height="42" style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_top.gif}) top left;"></td>
            <td width="61" height="42" valign="bottom" style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_topright.gif}) no-repeat top right;"></td>
          </tr>
          <tr>
            <td style="background:url(${Portal/Uri/Context/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(${Portal/Uri/Context/resource/portal-layout/images/mynovell_right.gif}) repeat-y top right;"></td>
          </tr>
          <tr>
            <td width="65" height="66" valign="top" style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_bottomleft.gif}) no-repeat top left;"></td>
            <td style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_bottom.gif}) repeat-x bottom left;"></td>
            <td width="61" height="66" valign="top" style="background:url(${Portal/Uri/Context/resource/portal-layout/images/mynovell_bottomright.gif}) no-repeat top right;"></td>
          </tr>
        </table>
  </td>
    </tr>
  </table>
  </body>
  </html>

Working with the layout API

The exteNd 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.