How the Shell Determines Header and Footer Content

When you build a portal in WebLogic Workshop, the shell that you select determines the header and footer content of the portal desktop. The shell can point to JSP or HTML files that contain the content, personalization, or other behavior you want to include in your headers and footers.

This topic contains the following sections:

Overview

The Shell File

The Portal File

Location of the Shell Resources

How the Shell Relates to Look & Feel

Summary

Overview

The following figure shows the area of a portal desktop controlled by the shell:

The shell could also be set up to include a left navigation region, as illustrated in the left navigation sample in the Sample Portal. So the shell really controls everything outside the main page book in a portal.

A shell is represented by an XML file (with .shell extension), as shown in the following figure.

Developers building portals with WebLogic Workshop are not the only users who can determine the shell used by a portal desktop. While developers create shells and select the default shell used by a portal, portal administrators ultimately determine the desktop shell.

After a portal administrator creates a desktop in the WebLogic Administration Portal, the administrator can change the desktop shell on the Dekstop Properties page.

The following section shows the shell XML file and describes how it is used to provide header and footer content.

The Shell File

The shell provides paths to the JSP or HTML files to be used in the desktop header and footer.

Shell files are stored in the following location: <portal_Web_project>/framework/markup/shell/. Following is the headerFooterVisitor.shell provided by BEA with the key attributes highlighted.

<?xml version="1.0" encoding="UTF-8"?>
<netuix:markupDefinition xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0 markup-netuix-1_0_0.xsd">
    <netuix:locale language="en"/>
    <netuix:markup>
        <netuix:shell
            title="Header-Footer Visitor Shell" 
            description="A header with a link and footer is included in this shell."      
            markupType="Shell" markupName="headerFooterVisitor">
            <netuix:head/>
            <netuix:body>
                <netuix:header>
                    <netuix:jspContent contentUri="/portlets/header/header.jsp"/>
                </netuix:header>
                    <netuix:break/>
                <netuix:footer>
                    <netuix:jspContent contentUri="/portlets/footer/footer.jsp"/>
                </netuix:footer>
            </netuix:body>
        </netuix:shell>
    </netuix:markup>
</netuix:markupDefinition>

The following table describes the shell attributes and shows how they are used to put content in the desktop header and footer:

This <element> or attribute... does this
title Required. The string used to display the name in the shell drop-down fields in WebLogic Workshop and the WebLogic Administration Portal.
description Optional. Description of the shell. The description is used in the WebLogic Administration Portal; when you select a shell in the portal Library, the description appears on the Shell Properties page.
markupType Required. The name of the type of component. Must always be "Shell".
markupName Required. The name for the shell. Each shell in the portal Web project must have a unique markupName.
<netuix:head/> Required. This element maps to the head.jsp skeleton file that renders the boundaries of the HTML <head> region.
<netuix:body> Required. This element maps to the body.jsp skeleton file that renders the boundaries of the HTML <body> region.
<netuix:header> Required. This element maps to the header.jsp skeleton file that renders the boundaries of the header region in HTML.
<netuix:footer> Required. This element maps to the footer.jsp skeleton file that renders the boundaries of the footer region in HTML.
<netuix:jspContent> Optional. Use this element to reference the JSPs or HTML files you want to use for content in the header and/or footer (by way of the contentUri attribute). To use this element, make sure the <netuix:header> and <netuix:footer> tags have opening and closing elements inside which this tag is inserted. Use the contentUri attribute to reference the JSP or HTML file relative to the portal Web project.

The shell XML is automatically added to the underlying XML in the .portal file.

The Portal File

Following is an example portal file, created with the Portal Designer, showing the inserted shell XML from the .shell file. The shell XML was inserted when the Shell property was set for the selected desktop in the Property Editor. When the .shell file is inserted into the .portal file, its job is finished in the rendering process and the .portal file is used to set the header and footer content.

<?xml version="1.0" encoding="UTF-8"?>
<portal:root xmlns:html="http://www.w3.org/1999/xhtml-netuix-modified/1.0.0"
    xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
    xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0 portal-support-1_0_0.xsd">
    <portal:directive.page contentType="text/html;charset=UTF-8"/>
    <netuix:desktop definitionLabel="defaultDesktopLabel" markupName="desktop" markupType="Desktop" title="New Portal Desktop">
        <netuix:lookAndFeel definitionLabel="avitek" description="The avitek look and feel"
            markupName="avitek" markupType="LookAndFeel" skeleton="default"
            skeletonPath="/framework/skeletons/" skin="avitek" skinPath="/framework/skins/" title="avitek"/>
        <netuix:shell description="A header with a link and footer is included in this shell."
            markupName="headerFooterVisitor" markupType="Shell" title="Header-Footer Visitor Shell">
            <netuix:head/>
            <netuix:body>
                <netuix:header>
                    <netuix:jspContent contentUri="/portlets/header/header.jsp"/>
                </netuix:header>
     
                    [XML for books, pages, and portlets...]
                <netuix:footer>
                    <netuix:jspContent contentUri="/portlets/footer/footer.jsp"/>
                </netuix:footer>

The portal file is a template with which multiple desktops can be created in the WebLogic Administration Portal. When used as a template, the portal file determines the default shell of any desktop created from it.

Location of the Shell Resources

The shell attributes in the portal file tell the portal which content to use for the portal header and footer when the portal is rendered in HTML. The portal in the previous example will use the following shell resources:

The headerFooterVisitor.shell example file contains two tags that point to the content to use in the header and footer, one inside the <header> element and one inside the <footer> element:

The locations of those files are highlighted in the previous figure. When the portal is rendered, those JSPs are converted to HTML and inserted into the header and footer regions of the portal. The JSP files can contain any content or functionality allowed in a JSP, including personalization.

The JSPs referenced by this example shell do not have to be called header.jsp and footer.jsp. They could be any JSPs in the portal Web project. However, the skeleton JSPs used to render the boundaries of the header and footer regions are always called header.jsp and footer.jsp in the skeleton framework. The skeleton JSPs are different than the JSPs referenced by the shell. The following section explains the difference in more detail.

How the Shell Relates to Look & Feel

While the shell controls the content of the area surrounding the main book of a portal, the look & feel determines which skeleton header.jsp and footer.jsp are used to render the boundaries and styles of the header and footer areas.

In the following examples, do not be confused by the identically named header.jsp for both the look & feel and the shell header. They are different files with different uses. The fact that both have the same name is coincidence.

Look & Feel (header.jsp skeleton)

The "avitek" look & feel in the portal file uses the "default" skeleton located in /sampleportal/framework/skeletons/default/. Included in the default skeleton is a file called header.jsp that is used to render the <header> element in the portal file.

<%@ page import="com.bea.netuix.servlets.controls.application.HeaderPresentationContext" %>
<%@ page session="false"%>
<%@ taglib uri="render.tld" prefix="render" %>
<%
    HeaderPresentationContext header = HeaderPresentationContext.getHeaderPresentationContext(request);
%>

<render:beginRender>
    <%-- Begin Body Header --%>
    <div
        <render:writeAttribute name="id" value="<%= header.getPresentationId() %>"/>
        <render:writeAttribute name="class" value="<%= header.getPresentationClass() %>" defaultValue="bea-portal-body-header"/>
        <render:writeAttribute name="style" value="<%= header.getPresentationStyle() %>"/>
    >
</render:beginRender>

[The JSP referenced in the shell <header> element is inserted here at rendering.]

<render:endRender>
    </div>
    <%-- End Body Header --%>
</render:endRender>

This is a simple skeleton file that, when rendered, produces the following HTML:

<!-- Begin Body Header -->
<div
    class="bea-portal-body-header"
>
</div>

<!-- End Body Header -->

The opening <div> tag uses a CSS class called "bea-portal-body-header" and then closes itself. The ending </div> tag at the end of rendering closes the <div> section. The JSP referenced in the shell header is inserted between the opening and closing <div></div> tags where its content is rendered as shown in the following example:

<!-- Begin Body Header -->
<div
    class="bea-portal-body-header"
>

[The JSP referenced in the shell <header> element is inserted here at rendering.]
</div>

<!-- End Body Header -->

The shell's header.jsp inserted into the <div> tag of the header region controls the content, styles, and behavior of the header content. The only elements provided by the look & feel are the <div> tag and the bea-portal-body-header style class.

For troubleshooting purposes, you could view the rendered portal and view the bea-portal-body-header class (contained in the avitek skin's body.css) to find out which style elements for which the look & feel is responsible. Following is the definition of bea-portal-body-header:

.bea-portal-body-header, .bea-portal-body-footer
{
    margin: 0px;
    padding: 1px;
    color: #C3C6B1;
}
.bea-portal-body-header
{
    font-size: large;
    font-weight: bold;
}

Summary

The shell selected for a portal desktop determines the content of the area surrounding the portal's main book. The shell XML file (.shell) includes references to the HTML or JSP files you want to appear in the desktop header and footer.

HTML and JSP files used in a header or footer can contain any content or functionality allowed in those types of files, including personalization in JSP files.

Once a shell is selected, its XML is inserted into the .portal XML file, which is the primary XML file used to control desktop rendering (.portlet XML files are used to render portlets).

While look & feel determines the physical boundaries of the header and footer and can include CSS styles and other skin elements generated by the skeleton header.jsp or footer.jsp files, the HTML or JSP files inserted in the header or footer by the shell control the content, styles, style overrides, and behavior of the header and footer.

Related Topics

The Portal User Interface Framework

How Look & Feel Determines Rendering

How Portal Components are Rendered

Creating Shells

Creating a Portal File

How Do I: Personalize a Desktop Header or Footer?