Portal User Interface Framework Guide
|
 |
 |
|
 |
 |
This document details how the portal framework turns a portal you develop in WebLogic Workshop (see Figure 1) into the portal desktop visitors see in a browser (see Figure 2). The goal of describing the portal framework is to help you develop and troubleshoot your portals. These topics enable you to look at a rendered portal in a browser and understand which pieces of the underlying framework you need to modify to get the results you want. In addition, the Look & Feel Editor is discussed. The Look & Feel Editor lets you interactively modify the text styles used by a portal.
The topics in this document describe key portal framework components and walk you through the portal rendering process. These topics include:
When you build a portal in WebLogic Workshop, the look & feels you use are the key to how your portal is rendered and what it looks like when it is rendered. This topic shows you how the different pieces of the look & feel framework are combined and configured to provide what the portal framework needs to render the look & feel in HTML.
This topic contains the following sections:
skin.properties FileThe look & feel encompasses the following:
A look & feel is represented by an XML file (with a .laf extension). As shown in the following figure, the .laf (avitek.laf) file is located in the lookandfeel folder of a portal project. In addition, the .laf file name (for example, avitek) can be selected in the Desktop properties panel.
Figure 3 Portal rendered in HTML.
Developers building portals with WebLogic Workshop are not the only users who can select the look & feel used by a portal desktop. While developers create look & feels and select the default look & feel used by a portal, portal administrators and visitors may ultimately determine the desktop look & feel. The following figures show how portal administrators and users can change the look & feel used by the desktop.
After a portal administrator creates a desktop in the WebLogic Administration Portal, the administrator can change the desktop look & feel on the Desktop Properties page, as shown in the following figure.
Figure 4 The Desktop Properties page
If visitor tools are enabled for the desktop, visitors can click the "Customize My Portal" link and change the desktop look & feel, as shown in the following figure.
The following section shows the contents of a look & feel XML-based .laf file and describes how it is used as the basis of portal desktop rendering.
Look & feel files point to the specific skin and skeleton to be used for the overall desktop look & feel.
Look & feel files are stored in the following location: <portal_Web_project>/framework/markup/lookandfeel. Following is the avitek.laf provided by BEA. The key attributes are 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:lookAndFeel
definitionLabel="avitek" title="avitek"
description="The avitek look and feel"
skin="avitek" skinPath="/framework/skins/"
skeleton="default" skeletonPath="/framework/skeletons/"
markupType="LookAndFeel" markupName="avitek"/>
</netuix:markup>
</netuix:markupDefinition>
The following table describes the look & feel file's key attributes.
When you select a Look & Feel in the WebLogic Workshop Property Editor for a selected desktop, the look & feel XML is automatically added to the underlying XML in the .portal file, as shown in the following section.
The following example portal file, created with the Portal Designer, shows the inserted look & feel XML (in bold) from the .laf file. 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 look & feel of any desktop created from it.
<?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 look & feel XML is inserted when the Look & Feel property is set for the selected desktop in the Property Editor. For example, in the following figure, the look & feel called avitek is selected.
Figure 6 Selecting a Look & Feel
When the .laf file is inserted into the .portal file, its job is finished in the rendering process and the .portal file is used to set look & feel.
The look & feel attributes in the portal file tell the portal which skin and skeleton to use to render the portal in HTML. The portal in the previous example will use the following skin and skeleton resources:
|
The Skins can also contain subdirectories for sub-skins, or themes (discussed in Look & Feel Overrides). |
The skeleton is made up of JSPs that map to and convert each portal component to HTML. The XML elements for the portal components in the This figure shows a clipped view of the skeleton contents. The subdirectories shown are skeleton themes and skeletons used for mobile devices. The JSPs in the Themes are discussed in Look & Feel Overrides. |
The icons used in portlet title bars are stored in the skin's /images directory. The portal framework reads the portal Web project's WEB-INF/netuix-config.xml file to determine which of these graphics to use for the portlet's different states and modes (minimize, maximize, help, edit, and so on).
Each skin has a skin.properties file, which is used by the portal framework to populate the <head> section of the rendered HTML, among other things. Included in skin.properties are references to the images directory, the CSS files containing the styles to be used in the HTML, and the JavaScript files containing the functions that will be used in the HTML.
Note: You can also create a file called skin_custom.properties in the same directory as skin.properties. Any entries you include in skin_custom.properties are also added to the HTML <head> region. This feature lets you customize the properties without having them overwritten by product updates.
The following will not be rendered:
.css files listed in the <head>. .js files listed in the <head>.That is why it is important to add references to all skin resources in skin.properties or skin_custom.properties.
The skin.properties or skin_custom.properties files can also contain skeleton path information that is used if skeleton attributes are omitted from the look & feel (.laf) file, as described in The Look & Feel File.
The following table shows an example of how entries in skin.properties for the active skin are converted to HTML <head> entries. Different skins may have different entries.
You can control the order in which the CSS and JavaScript entries are inserted into the HTML <head> section by adding
to a script entry, where the number is the order in which the entry should be inserted. All CSS entries are inserted first, followed by all script entries.
You can override the skin elements and skeletons on individual portal components so that those components have a different look & feel than the other portal components. For example, you can override the look & feel of a portlet so that it looks different than the other portlets on a page.
As part of each skin or skeleton, you can create sub-skins and sub-skeletons called "themes." Themes contain all or part of the resources contained in a skin or skeleton. For example, a skin theme can contain a /css subdirectory with a single CSS file, and a skeleton theme can contain a single JSP to render a portlet titlebar. Themes can be used on books, pages, and portlets.
Each theme requires a .theme file located in <portal_Web_project>/framework/markup/theme/. Following is a sample theme file:
<?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:theme
name="alert"
title="Alert Theme" description="A simple alert theme."
markupType="Theme" markupName="alert"/>
</netuix:markup>
</netuix:markupDefinition>
The theme file contains two key attributes:
The theme XML is inserted in the .portal around the XML for the book, page, or portlet to which the theme applies.
The following figures show where you set a theme in WebLogic Workshop and in the WebLogic Administration Portal.
Theme selection for a book, page, or portlet does not depend on the look & feel selected for a desktop. All themes are available for selection for all look & feels, whether or not the skins and skeletons for the look & feels contain the selected theme. If a skin or skeleton does not contain the selected theme, the theme is ignored. If both a skin and a skeleton theme exists for the selected look & feel, both are used.
The following figures show an example theme directory structure for the theme file, a skin theme, and a skeleton theme:
If skin or skeleton resources are not explicitly contained in a theme, the parent skin or skeleton resources are used. For example, if a skeleton theme uses only a JSP to render a portlet titlebar, the parent skeleton JSPs are used to render the rest of the portlet.
For skeletons, the ability to use parent resources is dependent on a file in the skeleton theme directory called skeleton.properties,which contains a single entry:
where ., .. is a relative path to the theme's own skeleton JSPs and to the parent skeleton's JSPs.
In the parent skin, the skin.properties must contain path information to its skin themes in the following format:
theme.alert.search.path: alert/images, images
The name of the theme directory is the second entry in the property. The path to the theme images is set (alert/images), along with the path to the parent skin's images directory (images) in case the theme images are an incomplete subset of the necessary images.
For any selected component in the Portal Designer, you can override CSS properties and the skeleton JSP used to render the component. With the portal component selected in the Portal Designer, set the property overrides you want in the Property Editor under Presentation Properties, as shown in the following figure.
When the portal desktop is rendered as HTML, the skeleton JSP you selected is used to render the component, and the style overrides you entered are automatically inserted into the XML of the .portal file.
The look & feel selected for a portal desktop serves as the basis for how the desktop is rendered in HTML. The look & feel XML file (.laf) points to a specific skin and a specific skeleton on the file system to use for rendering.
Skins are made up of framework images (like portlet titlebar icons), CSS files, and script files, such as JavaScript. Skeletons are JSPs that convert XML-based portal components to HTML.
Once a look & feel 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). The look & feel settings point to the file-based skin and skeleton resources that are used to generate and used in the rendered HTML.
The skin used in a look & feel contains a skin.properties and an optional skin_custom.properties file that contains references to all images, CSS files, and script files that are used by the skin. The entries in skin.properties and skin_custom.properties are converted to HTML <head> entries so that any framework images, CSS styles, and script functions used in the HTML are recognized.
You can override the look & feel for any book, page, or portlet by using themes; and using the Portal Designer and Portlet Designer Property Editor you can override CSS styles, attributes, and the skeleton JSP used to render desktops, books, pages, and portlet title bars and windows.
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:
The following figure shows the area of a portal desktop controlled by the shell:
Figure 8 Portal areas 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 WebLogic Workshop 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 Desktop Properties page.
Figure 10 Changing the desktop shell
The following section shows the shell XML file and describes how it is used to provide header and footer content.
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:
The shell XML is automatically added to the underlying XML in the .portal file.
Following is an example portal file, created with the Portal Designer, showing the inserted shell XML from the .shell file (in bold). 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.
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:
<netuix:jspContent contentUri="/portlets/header/header.jsp"/>
<netuix:jspContent contentUri="/portlets/footer/footer.jsp"/>
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.
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.
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;
}
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.
With the look & feel and shell selected for a portal desktop, the rendering service has the basic information it needs to convert a .portal XML file into a final HTML file.
This topic shows the rendering lifecycle, step by step, for a single portal component. The same rendering principles apply for all other portal components.
This topic includes the following sections:
There are three basic stages in the portal rendering process—a process that ultimately results in a portal desktop being displayed in a browser:
1. Building a portal in XML: In the portal development process, you use the Portal and Portlet designers in WebLogic Workshop to build .portal and .portlet files. Both types are XML files. As you build portals and portlets in WebLogic Workshop, the XML elements and attributes are automatically built under the surface.
The previous topics, How Look & Feel Determines Rendering and How the Shell Determines Header and Footer Content, described part of the XML-building process: how the look & feel and shell XML files are added to the portal XML file to provide rendering instructions.
2. Portal XML elements mapped to JSP skeleton files: The portal framework maps specific XML elements to specific JSP skeleton files. They are called skeleton files because they are used to render the physical boundaries and structure—the skeleton—of their portal components. For example, a portlet titlebar in a portlet XML file uses an element called <netuix:titlebar>. The portal framework knows to use the titlebar.jsp skeleton file to render the portlet titlebar.
3. JSP skeleton files and skin.properties are rendered as HTML: Each skeleton JSP file performs its own processing, such as retrieving property values you set in the WebLogic Workshop Property Editor (and were automatically added to the portal XML file), and generates the appropriate HTML for the portal component. The skin.properties and optional skin_custom.properties files for the selected look & feel are converted to image path entries, CSS file entries, and script file entries in the HTML <head> area.
The following figure is a simplified illustration of the rendering process.
Figure 12 Portal rendering process
This topic will expand on these three stages using the rendering lifecycle of a single portal component as an example.
Before going into greater detail on the rendering process, it is important to understand the difference between viewing a portal in the development environment (WebLogic Workshop) and viewing it in the administration/end user environment (WebLogic Administration Portal/browser). The three-stage rendering process occurs in slightly different ways in the two different environments. The following section describes the basic principles of each.
The .portal file you create in WebLogic Workshop is a template. In this template you create books, pages and portlets and define defaults for them. When you view the .portal file with your browser the portal is rendered in "single file mode," meaning that you are viewing the portal from your file system as opposed to a database. The .portal file's XML is parsed and the rendered portal is returned to the browser. The creation and use of a .portal is intended for development purposes, but you can access a .portal file in production. Because there is no database involved you cannot take advantage of features such as user customization or entitlements.
Once you have created a .portal file you can use it to create desktops for a production environment.
A desktop is a particular view of a portal that visitors access. A portal can be made up of multiple desktops, making the portal a container for desktops. A desktop contains all the portlets, content, shells, layouts, and look & feel elements necessary to create individual user views of a portal.
When you create a desktop based on the .portal file in the WebLogic Administration Portal, the .portal and its resources are placed into the database. The settings in the .portal file, such as the look & feel, serve as defaults to the desktop. Once a new desktop is created from a .portal template, the desktop is decoupled from the template, and modifications to the .portal file do not affect the desktop, and vice versa. For example, when you change a desktop's look & feel in the WebLogic Administration Portal, the change is made only to the desktop, not to the original .portal file. When you view a desktop with a browser it is rendered in "streaming mode" (from the database). Now that a database is involved, desktop customizations can be saved and delegated administration and entitlements can be set on portal resources.
The following table compares streamed and file based portals in more detail:
This section illustrates the rendering lifecycle of a book, which will help you understand the rendering lifecycle of other portal components, such as pages and portlets.
This section contains the following topics:
This section describes steps that populate and configure the .portal XML file.
When you select the look & feel for a desktop, the look & feel file determines which skin and skeleton is used to render all desktop components. In the following example, the "avitek" look & feel has been selected, which uses the "avitek" skin and the "default" skeleton. The look & feel XML is added to the .portal XML file.
The skin and skeleton come into play later in the rendering process, when the desktop is viewed with a browser. Before that happens, the book that will be used to illustrate the rendering process will be added to the portal.
In this section a book is added to the desktop in the .portal file and configured. Books can also be added by portal administrators in the WebLogic Administration Portal, which adds the book directly to the database.
The following figure shows a book control being dragged onto the desktop.
Figure 13 Dragging a control to the Desktop
After the book is added to the desktop, the book title is changed from "New Book" to "My Book," and the navigation style is set to Multi Level Menu, as shown in the following figure.
Navigation controls the way a book's sub-books and pages are accessed. The single-level menu provides text links/tabs to sub-books and pages, and the multi-level menu provides a drop-down menu to access sub-books and pages. (Books must be added to books rather than to pages inside books for drop-down navigation to work. So in the following example, for the multi-level menu to produce a drop-down menu, you would need to drag a new book control into Main Page Book, right next to Page 1, as shown in the following figure.)
Figure 14 Arranging portal components
After the Navigation style is set on My Book, the following is what the book looks like in XML in the .portal file. If you add a book in the WebLogic Administration Portal, the XML is added to the database. This XML is used as the basis for the rendering of the book.
<netuix:book defaultPage="newPage.1" definitionLabel="my_book_3"
markupName="book" markupType="Book" title="My Book">
<netuix:multiLevelMenu
description="This menu can navigate across may nested books."
markupName="multiLevelMenu" markupType="Menu" title="Multi Level Menu"/>
<!-- in this example, the nested page content has been removed -->
</netuix:book>
When the desktop is viewed in a browser, the portal framework reads the XML elements and uses the skeleton path to map the desktop's XML elements to skeleton JSPs. The following examples show which elements in the book XML are mapped to skeleton JSPs and which skeleton JSPs are used to render the elements.
|
Once rendering has been handed off to the JSPs, the JSPs perform the tasks necessary for conversion to HTML. Following are the book.jsp, multilevelmenu.jsp, and submenu.jsp used in this example. Comments are added to describe what the JSPs are doing.
The book.jsp serves as a high-level container for the book's menu and the book's child books and pages. Comments in the JSP code are highlighted in bold text.
<%@ page import="com.bea.netuix.servlets.controls.page.BookPresentationContext,
com.bea.netuix.servlets.controls.page.MenuPresentationContext"
%>
<%@ page session="false"%>
<%@ taglib uri="render.tld" prefix="render" %>
<render:beginRender>
<%-- The content inside the <render:beginRender> tag is processed first
and ultimately renders whatever is inside it. In most cases, the
skeletons produce an opening <div> HTML tag with specific attributes
such as CSS classes.
The following block determines where the book falls in the desktop
hierarchy (whether it is the top-level book or a nested book). It
also sets the base name of the CSS class to use (bea-portal-book)
and appends different endings to the base class to apply a
different CSS class for each book context. Only processing,
not HTML rendering, occurs in this block.
--%>
<%
BookPresentationContext book =
BookPresentationContext.getBookPresentationContext(request);
MenuPresentationContext menu = (MenuPresentationContext)
book.getFirstChild("page:menu");
String bookClass = "bea-portal-book";
String useBookClass = bookClass;
if (book.isDesktopBook())
{
bookClass += "-primary";
useBookClass = bookClass;
}
else if (book.isLikePage())
{
useBookClass += "-invisible";
}
String bookContentClass = bookClass + "-content";
%>
<%-- The next block begins the actual HTML rendering, beginning with
the comment "Begin Book" followed by an opening <div> HTML
tag. Notice the JSP tags used before the closing bracket of the
<div> tag. These populate the div tag with style attributes.
The methods retrieve any presentation property override values
you entered in the WebLogic Workshop Property Editor for the book.
For the "class" attribute, the default value is useBookClass,
which earlier is set to "bea-portal-book". (If through getting
the context the book was found to be the top-level book, the value
of useBookClass would be "bea-portal-book-primary".)
With no overrides, the useBookClass variable will produce the
following HTML, because the book is acting like a page:
<div
class="bea-portal-book-invisible"
>
The style sheet class is provided by the skin, and the CSS file
containing the class is referenced in the skin's skin.properties
file and added to the HTML <head> region.
--%>
<%-- Begin Book --%>
<div
<render:writeAttribute name="id" value="<%= book.getPresentationId() %>"/>
<render:writeAttribute name="class" value="<%=
book.getPresentationClass()%>" defaultValue="<%= useBookClass %>"/>
<render:writeAttribute name="style" value="<%= book.getPresentationStyle() %>"/>
>
<%-- The following JSP tag gets the names of the pages and books it will
display in its navigation menu, and based on the navigation element
used in the portal XML file (in this case netuix:multiLevelMenu),
uses the corresponding menu JSP (multilevelmenu.jsp) to render the menu
in this position of the HTML.
--%>
<render:renderChild presentationContext="<%= menu %>"/>
<%-- The following block provides a <div> HTML container for the
book's content area--the child books and pages. Again, it uses
a JSP tag to set the style sheet "class" attribute.
--%>
<%-- Begin Book Content --%>
<div
<render:writeAttribute name="class" value="<%= book.getContentPresentationClass()%>" defaultValue="<%= bookContentClass %>"/>
<render:writeAttribute name="style" value="<%= book.getContentPresentationStyle() %>"/>
>
</render:beginRender>
<%-- The closing </render:beginRender> tag signals the portal framework
to stop rendering the book. After the book's children and their
children are rendered, the portal framework uses the following
<render:endRender> tag to close the book's parent HTML tags.
--%>
<render:endRender>
</div>
<%-- End Book Content --%>
</div>
<%-- End Book --%>
</render:endRender>
Following is a description of the multilevelmenu.jsp, which is used by the book to render the navigation menu for the book's child books and pages.
The multilevelmenu.jsp is rendered inside the book container and provides the boundaries for multi-level menus on books. This JSP also uses submenu.jsp to perform the actual rendering of the menu links.Comments are highlighted in bold text.
<%@ page import="com.bea.netuix.servlets.controls.window.WindowPresentationContext,
com.bea.netuix.servlets.controls.page.BookPresentationContext,
com.bea.netuix.servlets.controls.page.MenuPresentationContext,
java.util.List,
java.util.Iterator,
com.bea.netuix.servlets.controls.page.PagePresentationContext,
com.bea.netuix.servlets.controls.window.WindowCapabilities" %>
<%@ page session="false"%>
<%@ taglib uri="render.tld" prefix="render" %>
<%-- The following block determines where the book falls in the desktop
hierarchy (whether it is the top-level book or a nested book). It
also sets the base name of the CSS class to use (bea-portal-book)
and defines different menu style classes by appending different
endings to the base class. Only processing, not HTML rendering,
occurs in this block.
--%>
<%
BookPresentationContext book =
BookPresentationContext.getBookPresentationContext(request);
MenuPresentationContext menu =
MenuPresentationContext.getMenuPresentationContext(request);
String bookClass = "bea-portal-book";
if (book.isDesktopBook())
{
bookClass += "-primary";
}
final String menuClass = bookClass + "-menu";
final String menuContainerClass = menuClass + "-container";
final String menuItemClass = menuClass + "-item";
final String menuItemActiveClass = menuItemClass + "-active";
final String menuItemLinkClass = menuItemClass + "-link";
final String menuHookClass = menuClass + "-hook";
final String menuButtonsClass = menuItemClass + "-buttons";
List menuChildren = menu.getChildren();
%>
<render:beginRender>
<%-- The content inside the <render:beginRender> tag is processed first
and ultimately renders whatever is inside it, such as opening <div>
