7 Developing Page Templates

Use 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 JDeveloper, you can design and develop new page templates for building portal pages.

Topics:

7.1 Introduction to Developing Page Templates

This section includes the following topics:

7.1.1 Understanding Page Templates

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 Oracle Fusion Middleware 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.

7.1.2 Understanding Page Template Structure

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

Description of Figure 7-1 follows
Description of "Figure 7-1 Sample Portal that Uses a Page Template"

7.1.3 Understanding Page Template Layout

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

7.1.4 Understanding Page Template Layout Components

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:

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

Description of Figure 7-2 follows
Description of "Figure 7-2 Page Template Code and Generated Stretching Layout: Example 1"

Figure 7-3 Page Template Code and Generated Stretching Layout: Example 2

Description of Figure 7-3 follows
Description of "Figure 7-3 Page Template Code and Generated Stretching Layout: Example 2"

7.2 Best Practices for Developing Page Templates

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:

  • Minimize the use of embedded task flows. For examples, refer to the latest out-of-the-box page templates included with WebCenter Portal, described in About Built-in Page Templates in WebCenter Portal in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.

  • Minimize the use of ADF layout components, using panelGridLayout to implement your page template structure. The fewer ADF layout components, the easier it is to apply skins.

  • Avoid using images for decorative purposes (such as rounded corners). Consider using CSS instead of images.

  • Defer loading of ADF components, such as menus and dialogs, where possible. This can be controlled through ADF such as contentDelivery, childCreation, and so on.

  • Avoid elements that require extra time in rendering page templates and try to substitute for elements that require less processing time.

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:

  • A top navigation page template exposes the portal navigation in header area. Top navigation makes effective use of the horizontal space on the page, and is recommended when there are seven or fewer top level pages in the portal navigation. This page template design generally has a header, page and footer sections, and is an ideal starting point for sites that require a flowing layout.

  • A side navigation page template exposes the portal navigation in a sidebar on the left side of the page. The vertical nature of side navigation allows for a more lengthy list of navigation items, and is recommended when there are more than seven top level pages in the portal navigation. Choose a side navigation template for more complex navigation models.

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 (http://jdevadf.oracle.com/adf-richclient-demo/faces/visualDesigns/index.jspx). Select Page or Page Template from the View Source menu for a component to see what tags and attributes are used as well as what the component structure looks like for the page.

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, showFooter specifies whether or not to show the page footer.

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.

go components such as goButton and goLink have little to no client side footprint since they do not carry client side functionality. They are also preferred over command components (commandButton, commandLink) for general navigation in portals because they enable URLs that are optimized for search engines.

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:

7.2.1 Best Practices for Creating Stretching Layouts

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

7.2.2 Best Practices for Creating Flowing Layouts

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".

7.2.3 Best Practices for Developing Page Templates That Can Be Edited at Runtime

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)

panelCustomizable

Box

outputText

HTML Markup

goLink

Hyperlink

goImageLink

Image

showDetailFrame

Movable Box

richTextEditor

Text

inlineFrame

Web Page

7.2.4 Best Practices for Customizing the Appearance of Components

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

7.2.5 Best Practices for Defining Scrolling in a Page Template

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.

7.2.6 Best Practices for Defining Margins, Borders, and Padding

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

7.3 Creating a Page Template

This section contains the following subsections:

7.3.1 About Creating Page Templates

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 Oracle Fusion Middleware 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.

7.3.2 How to Create a Page Template

This section describes how to create a WebCenter Portal asset application for a new page template.

To create a custom page template:

  1. Create a WebCenter Portal asset application for the asset, selecting Page Template as the Asset Type.

    Figure 7-4 Page Template Asset Type

    Description of Figure 7-4 follows
    Description of "Figure 7-4 Page Template Asset Type"

    See Creating a WebCenter Portal Asset Application for more information about creating WebCenter Portal asset applications.

    A JSPX file is created for the page template.

    Figure 7-5 Page Template JSPX File

    Description of Figure 7-5 follows
    Description of "Figure 7-5 Page Template JSPX File"

    For more information about the artifacts created when you create an asset application for a new page template, see What You May Need to Know About Page Template Artifacts.

  2. Continue by editing the contents of the JSPX file as described in Editing a Page Template.

7.3.3 What You May Need to Know About Page Template Artifacts

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

Description of Figure 7-6 follows
Description of "Figure 7-6 Page Template Asset Application Artifacts"

7.4 Editing a Page Template

After creating a WebCenter Portal asset application and initial page template, continue by adding or modifying elements.

To edit a page template:

  1. In the Application Navigator, right-click the JSPX file of the page template that you want to edit, and choose Open.
  2. In the editor, make required changes to the layout and content of the page template by dragging components from the Component Palette.

    For more information about how to build your page template, see Introduction to Developing Page Templates and Best Practices for Developing Page Templates.

    The built-in page templates provide useful examples of page templates, and see also Page Template Tutorials and Examples.

    For general information about JSF page templates, see Using Page Templates in Oracle Fusion Middleware Developing Web User Interfaces with Oracle ADF Faces.

  3. Save your changes.

7.5 Adding a Floating Toolbar to 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.

To add the floating toolbar to a custom page template:
  1. Include the following xml namespace declaration  (if not already present):
  2. Within the xml namespace declaration, include the following reference to the floating toolbar: 
    <wcdc:portalToolbar id="ptbdc"/>

    Figure 7-7 shows how the floating toolbar with the Contribute option will appear when the page template includes the toolbar.

    Figure 7-7 The Contribute Button in the Floating Toolbar

    The Contribute button in the floating toolbar.
For more information, see About Content Contribution and Publishing in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.

7.6 Publishing a Page Template

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.

7.7 Page Template Tutorials and Examples

The supplementary tutorials and examples listed in this section provide additional information about page templates.