This chapter describes how to use Oracle JDeveloper to create, edit, and publish page templates for use in WebCenter Portal.
Page templates provide the structure for common areas in portal pages. Using Oracle JDeveloper, you can design and develop page templates for portal pages displayed in WebCenter Portal.
This chapter includes the following topics:
This section includes the following topics:
Page templates define how individual pages and groups of pages display on a user's screen, and help to ensure that the pages in a portal are consistent in structure and layout.
If you change a page template, then all pages that reference that template automatically inherit the changes.
Note:
For general information about page templates, see Using Page Templates in Developing Web User Interfaces with Oracle ADF Faces.
For tips and best practices for creating page templates for use in Oracle WebCenter Portal, see Best Practices for Developing Page Templates. Oracle recommends that you use Oracle JDeveloper to develop page templates for use in WebCenter Portal. You can also develop page templates in WebCenter Portal, but the editing capabilities are limited.
When fully developed, you can publish page templates directly to WebCenter Portal as a shared asset or to a specific portal for immediate use or for testing. For more information, see Publishing a Page Template.
Typical elements of a page template include:
Header, content area (different in each page), and footer. The header and footer commonly include brand-specific elements. For example, a header usually includes a logo and possibly a slogan, and a footer usually includes contact and copyright information.
Navigation. A page template can expose the navigation for a portal in many ways. For example, on a mobile device, portal navigation may be shown as a popup or slide in/out. On a desktop browser, portal navigation is typically shown along the top of the page, or down the side of the page.
Branding elements. For example, a page template my include a company logo, slogan, or copyright message.
Links and actions. For example, a log in/log out link, drop-down menus, or global links (such as links to send a mail message to the web administrator or to display a privacy statement).
Conditional elements. For example, some elements on the page might differ depending on whether the user is public or authenticated or depending on the user's role and privileges.
Figure 7-1 shows a sample application based on a page template that illustrates these elements.
Figure 7-1 Sample Portal that Uses a Page Template
One of the most important aspects of page template design is the layout of components, both elements of the template and page content.
There are two basic strategies:
A flowing layout is the most typical layout. Components are arranged side by side or one below the other, displayed using their natural size. When the content of the page extends beyond the size of the browser window, the browser displays scroll bars on the page.
A stretching layout may be a suitable choice when your page content fills a large area, or you want the page content to grow and shrink depending on the size of the browser window. Components are stretched to occupy the available space on the page. For example, a stretching layout may be suitable when a page contains a table or graph that you want to fill up the whole content area, no matter what size it is. Another example is a page that contains an editing area, where you want the editor to be exactly as tall and wide as the space given to the content area. This layout has a region for the page content, and adds scroll bars to the region on the page when the content cannot be contained within the size of the browser window. In other words, individual components display scroll bars (which might mean that you have multiple scroll bars on one page).
Stretching enables you to maximize the usage of the viewable area. You can use tabs, accordions, menus, and popups to expand your viewable area. When scroll bars are added to the page, the navigation area, page header, and page footer remain in view while the content area scrolls.
Because most web sites use a flowing layout, you will probably also want to use a flowing layout as it will likely feel more familiar to your users. However, stretching layouts are good for dashboards and applications that are rich in nature or when you want to mimic a desktop experience. You can also combine flowing and stretching layout on the same page.
Vertical Behavior
Depending on whether your layout is flowing or stretching, the vertical behavior of the page differs as follows:
Flowing layout:
The header and/or footer might not always be visible
The height of the page is calculated based on the page contents
The content is never stretched vertically
The browser might display a scroll bar
Stretching layout:
The header and footer are always visible
The height of the page is determined by the browser window
The content is stretched vertically
The content area might display a scroll bar
Horizontal Behavior
Depending on whether your layout is flowing or stretching, the horizontal behavior of the page differs as follows:
Flowing layout:
If your page includes a side bar (for example, left-side navigation), the side bar might not always be visible
The width of the page is calculated based on the components
Some components might be stretched to fill up existing space
The browser might display a scroll bar
Stretching layout:
If your page includes a side bar (for example, left-side navigation), the side bar is always visible
The width of the page is determined by the browser window
The content is stretched horizontally
The content might display a scroll bar
The underlying structure of a page template is provided by Oracle Application Development Framework (ADF) layout components.
After you decide on the appropriate layout to use for your page template (see Understanding Page Template Layout), you will use ADF layout components to create your page template. This is a complex task, and requires knowledge of the ADF components that will achieve the structure and layout you require, and best practices to employ (see Best Practices for Developing Page Templates).
Note:
For details on what different layout components look like, see the ADF Faces Rich Client demo online tool:
http://jdevadf.oracle.com/adf-richclient-demo/faces/visualDesigns/index.jspx
In the demo tool, you can select Page or Page Template from the View Source menu to see what layout components and attributes are used to achieve the page structure.
Figure 7-2 and Figure 7-3 illustrate common ADF components used in a page template layout, showing the page template code followed by the generated layout:
af:panelGridLayout
—a versatile layout component that uses rows (gridRow
) and cells (gridCell
) to define a structured layout. This component is the preferred general layout component as it offers a small client side footprint while being very flexible in layout capabilities. It allows you to more naturally define areas of the page to match your desired layout in the form of rows and columns. With panelGridLayout
, you can easily specify fixed or variable column widths (% or pixels), which cannot be done as easily with other layout components. See Figure 7-2.
af:panelGroupLayout
—a flowing series of components arranged horizontally, vertically, or in scrollable structures. Typically, panelGroupLayout
is used with flowing layouts, and with flowing content inside a stretching layout. It provides vertical and horizontal scroll bars if the content does not fit into the available space. See Figure 7-2 and Figure 7-3.
af:panelSplitter
—a stretched box divided into two user-modifiable sections. See Figure 7-3.
Figure 7-2 Page Template Code and Generated Stretching Layout: Example 1
Figure 7-3 Page Template Code and Generated Stretching Layout: Example 2
Because page templates are present in every page of a portal, the design of your page templates should be carefully planned to optimize their performance and conform to best practices.
This section provides tips for developing page templates for WebCenter Portal (as a shared asset), or a specific portal.
Note:
Oracle recommends that you use JDeveloper to develop page templates for portals. You can also develop page templates in Oracle WebCenter Portal, but the editing capabilities are limited.
When fully developed, you can publish page templates to WebCenter Portal as a shared asset or to a specific portal for immediate use or for testing. Alternatively, you can export the page template to a file and upload the page template to WebCenter Portal later.
For more information, see Creating a Page Template, Editing a Page Template, and Publishing a Page Template.
Table 7-1 provides a quick reference summary of considerations and guidance for achieving the best results out of your page templates.
Table 7-1 Best Practices Summary for Page Templates
Considerations | Best Practices |
---|---|
Performance |
While all of this section is aimed at improving the performance of your page templates, there are a few general tips to keep in mind as overall best practices:
|
Layout |
One of the most important aspects of page template design is how to lay out components, both elements of the template and page content. Page templates can have a flowing layout or a stretching layout. For more details about these two strategies, see Understanding Page Template Layout. As a page template developer, you can control whether the content facet is in a stretching or flowing region of the page. Page content must be created taking the layout strategy into consideration. Once you decide on the best strategy for your page templates, see the following sections for tips on creating the layout you choose: |
Navigation |
A page template can expose the navigation for a portal in many ways. For example, in a desktop browser, portal navigation is typically shown along the top of the page, or down the side of the page:
On different devices, navigation can be exposed differently. For example, in page templates optimized for mobile devices, navigation can be provided as either a popup or slide in/out. |
Skin |
Each page template works together with a skin to determine the overall look and feel of the pages in your portal. While the page template controls the structure of components on the page, the skin controls the visual appearance of those components, such as the colors, fonts, and other aspects such as the position, height, and width of components on the page. Each page template can define a preferred skin to identify the skin that works best with that page template. When the page template is selected as the default page template for a portal or as the system default, the default skin automatically updates to the page template's preferred skin. For more information, see Developing Skins. |
Runtime behavior |
If you develop a page template in JDeveloper that you plan to allow authorized users to edit in Composer at runtime, follow the tips provided in Best Practices for Developing Page Templates That Can Be Edited at Runtime. |
Components |
For details on what different ADF layout components look like, see the ADF Faces Rich Client demo online tool ( Because a page template layout can be changed, create pages and design custom components that display properly in flowing and stretching context. For tips on customizing the appearance of components, see Best Practices for Customizing the Appearance of Components. |
Scrolling |
Add scrollbars only around flowing island content. For tips on implementing scrollbars, see Best Practices for Defining Scrolling in a Page Template. |
Margins, borders, and padding |
Due to browser CSS Box Model Rules, defining margins, borders and padding on components might be complex. For tips on resolving the complexities of defining margins, borders and padding on components, see Best Practices for Defining Margins, Borders, and Padding. |
Attributes |
Consider attributes that can be set in your page templates or pages that use the page templates. For example, A page template without attributes is syntactically correct. However, page template attributes are useful when you want to use one page template for several pages where the template should render slightly differently. Information about using attributes in your page templates is provided throughout this chapter, including Creating a Page Template. |
Links |
To add links to page templates, copy components provided in the out-of-the-box page templates to include links navigation, menus, breadcrumbs, buttons, and images.
|
Internationalization |
To create page templates with internationalization techniques in mind, see Guidelines for Building Multilanguage Portals for information about recommended practices such as storing static text in resource bundle files. |
Naming page templates (display name) |
The display name is exposed to users when creating a new page. For this reason, you should make the page template name something that helps users quickly identify which type of pages the template should be used for. |
This section includes the following topics:
If your page template is best suited to a stretching layout, follow these tips as you develop the layout.
For more information about different layouts, see Understanding Page Template Layout.
Build the outer structure with containers that can be stretched and can stretch their children. Inside your document
component, use containers such as panelGridLayout
(Figure 7-2) with rows (gridRow
) and cells (gridCell
), and panelSplitter
(Figure 7-3).
Note:
Each layout or panel component's tag documentation identifies whether it is stretchable and how to achieve it in its "Geometry Management" documentation. Some components have attributes to determine whether children will be stretched or not. For example: document
has a maximized
attribute, showDetailItem
has a stretchChildren
attribute.
Create flowing islands. Inside of the stretchable outer structure, create islands of flowing (non-stretched) components. To make this transition from stretching to flowing, use panelGroupLayout
with layout="scroll"
or layout="vertical"
since it supports being stretched but will not stretch its children.
On stretching components, set dimensionsFrom="auto"
so that the stretching component (for example, panelStretchLayout
) will only try to stretch its child if it itself is being stretched. If it is not being stretched, then it will flow (not stretch) its children.
Do not stretch something vertically (by using a height with a percent value) when inside a flowing container.
Do not use the position
CSS property in an inlineStyle
. Doing so will impede the ability to override this property with a style specified in the skin.
Note:
The following components are just some of the components that cannot be reliably stretched:
Most input components
panelBorderLayout
panelFormLayout
panelGroupLayout
(with layout="default"
)
panelGroupLayout
(with layout="horizontal"
)
panelHeader
(with type="flow"
)
panelLabelAndMessage
panelList
panelGrid
If your page template is best suited to a flowing layout, follow these tips as you develop the layout.
For more information about different layouts, see Understanding Page Template Layout.
Use panelGridLayout
with rows (gridRow
) and cells (gridCell
) to define a structured layout that will flow.
To avoid multiple scroll bars, do not nest scrolling panelGroupLayout
components, instead use layout="vertical"
.
Most stretchable ADF components also work in flowing context with dimensionsFrom="auto"
.
To stretch a component horizontally, use styleClass="AFStretchWidth"
(instead of inlineStyle="width:100.0%"
).
Working with customizable components:
In panelCustomizable
, use layout="auto"
to detect whether to stretch its children.
To support flowing and stretching layouts, use showDetailFrame
with stretchChildren="auto"
.
To create a page template at design time (in Oracle JDeveloper) that is suited to being editable at runtime (in Oracle WebCenter Portal), follow these tips.
Add components from the Composer group in the Component Palette.
Do not add pageCustomizable
to a page template.
Add at least one panelCustomizable
component, which provides a container with horizontal or vertical layout that holds other components.
Inside a panelCustomizable
component, add ADF components (such as outputText
, richTextEditor
, or goLink
) surrounded by a showDetailFrame
, which provides a chrome for a component that enables you to add actions like show, hide, and move. You can edit the frame or the embedded component properties.
Caution:
Use this technique sparingly, as showDetailFrame
components impact processing time. If the end user is not expected to move components around, do not wrap them in a showDetailFrame
.
Many of the components available to add to a page at design time are also available at runtime in the resource catalog. Table 7-2 maps design time components to runtime components.
Table 7-2 Component Mapping: Design time to Runtime
Design Time (JDeveloper) | Runtime (WebCenter Portal) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To customize the appearance of components, follow these tips.
For custom styling, use Cascading Style Sheets (CSS), which is easy to maintain and can be changed without changing the page template source. For example, make the background color of a page blue using the CSS code background-color: blue
.
Use a custom skin for consistently modified appearances if the existing skin doesn't provide all that you need.
For instance-specific alternative styling, use the styleClass
attribute. Keep the corresponding style definitions in an easy-to-maintain location such as in a custom skin (recommended) or in a style provided by the af:resource
tag.
As a last resort, use component attributes such as inlineStyle
, contentStyle
, and labelStyle
. These are harder to maintain as they are scattered throughout components rather than collected in a single style sheet, contribute more to the page's raw HTML size, and may not even be needed if one or more of the above mechanisms are used. Styles are directly processed by the web browser, which gives you a great deal of power but at the cost of being error-prone.
Browsers do not support all styles on all elements and certain combinations of styles produce non-obvious results. Here is some guidance on style configurations to avoid:
An inlineStyle
with a height
value with %
units
An inlineStyle
with a width
value between 90%
and 100%
(use styleClass="AFStretchWidth"
or styleClass="AFAuxiliaryStretchWidth"
instead)
An inlineStyle
with height
, top
, and bottom
values
An inlineStyle
with width
, left
, and right
values
An inlineStyle
with a position
value
In a child being stretched by a parent component, an inlineStyle
with width
or height
values
To define scrolling in a page template, follow these tips.
Try to avoid the need for end users to scroll horizontally by designing the page content to occupy the available screen size.
Add scrollbars only around flowing island content. The recommended transition component for switching from a stretching outer frame into a flowing island is the panelGroupLayout
with layout="scroll"
. If the contents of this panelGroupLayout
cannot fit in the space allocated, the browser will determine whether scrollbars are needed and will add them automatically.
Do not nest scrolling panelGroupLayout
components because this will make the user see multiple scrollbars. Also, this should only be used at transitions from stretching to flowing areas and since you should not have stretching areas inside of flowing areas, you would generally never end up with nested scrollbars. It is best to minimize the number of areas that users must scroll in order to see what they are looking to find. Take time to consider what scrolling users will need. In cases where undesired scrollbars exist, you may want to change the layout
attribute of the panelGroupLayout
to vertical
.
Due to browser CSS Box Model Rules, defining margins, borders and padding on components can be complex. In many cases, to apply these kinds of styles, you need to use multiple components together.
In a scrolling area, you can add an extra panelGroupLayout
with layout="vertical"
with the padding defined on it, inside of the outer panelGroupLayout
with layout="scroll"
.
In a stretching area, you may need to wrap a panelGroupLayout
component inside a panelGridLayout
with spacers inside gridCell
components. See Figure 7-2.
Note:
Refer to the Navigation-Master-Detail, Tiled Flowing, and Tiled Stretching layout pattern examples for various mechanisms to apply padding:
http://jdevadf.oracle.com/adf-richclient-demo/faces/feature/layoutBasicTest.jspx
This section contains the following subsections:
Before you can design your page template, you must first create a WebCenter Portal Asset application for the page template.
Before you create a page template, be sure to read through Best Practices for Developing Page Templates.
Note:
Oracle recommends that you use JDeveloper to develop page templates for Oracle WebCenter Portal. You can also develop page templates in WebCenter Portal, but the editing capabilities are limited.
When fully developed, you can publish a page template directly to WebCenter Portal as a shared asset or to a specific portal for immediate use or for testing. Alternatively, you can export the page template to a file and upload the page template to WebCenter Portal later
For more information, see Editing a Page Template and Publishing a Page Template.
For examples of features that you can include in your own page templates, refer to the built-in page templates provided with WebCenter Portal, specifically the latest responsive page templates (Mosaic and Unicorn), and other page templates that minimize the use of task flows and include the performance-optimizing panelGridLayout
component, which uses rows (gridRow
) and cells (gridCell
) to define a structured layout. See About Built-in Page Templates in WebCenter Portal in Building Portals with Oracle
WebCenter Portal.
You can start by copying and pasting one of one of the built-in templates into JDeveloper, or you can build an entirely new page template from scratch. Even if you do not intend to base your page templates on the built-in ones at all, it is still worth studying them for ideas. For example, the built-in page templates include a login form, and a good example of navigation visualization, which you can modify according to your requirements.
This section describes how to create a WebCenter Portal asset application for a new page template.
To create a custom page template:
Creating a page template asset application produces a default template, with the following artifacts:
A JSPX file containing the page elements for the page template (for example, PageTemplate1.jspx
)
The corresponding page definition file for the page template (for example, PageTemplate1PageDef.xml
)
Both of these files appear in the Application Navigator as shown in Figure 7-6.
Figure 7-6 Page Template Asset Application Artifacts
After creating a WebCenter Portal asset application and initial page template, continue by adding or modifying elements.
To edit a page template:
When users with the Contribute Page Content
permission view a page, they will see a floating toolbar with a Contribute option when the page template includes the toolbar.
After creating a page template and editing its JSPX file, the next step is to publish and test the template in WebCenter Portal.
For instructions on how to publish a page template as a shared asset, or to a specific portal as a portal asset, see Publishing WebCenter Portal Assets.
The supplementary tutorials and examples listed in this section provide additional information about page templates.
Dissecting a Page Template. Analyzes the details of a simple page template, including recommended practices.
Oracle WebCenter Portal Online Training: Creating and Using Page Templates in Oracle WebCenter Portal Applications. Provides a recorded presentation and slides to create and use page templates for a portal in an earlier release.
http://www.oracle.com/technetwork/middleware/webcenter/portal/learnmore/pagetemplates-1438595.pdf
Optimizing WebCenter Portal Mobile Delivery. Identifies and analyzes some common WebCenter Portal performance bottlenecks related to page weight and describes a generic approach that can streamline a portal while improving the performance and response times. Of particular interest in the context of developing page templates is the section "Page Design and Component Choices." A sample application is available for download.
Working with Links in WebCenter Application. Describes considerations for using links. Pertinent to page templates are links in menus, breadcrumbs, buttons, and images.
http://www.ateam-oracle.com/working-with-links-in-webcenter-application/