19 Creating and Reusing Fragments, Page Templates, and Components (ofm-wui-dg 11.1.1.6)

This chapter describes how you can create reusable content and then use that content
to build portions of your JSF pages or entire pages.
This chapter includes the following sections:
■ Section 19.1, "Introduction to Reusable Content"
■ Section 19.2, "Using Page Fragments"
■ Section 19.3, "Using Page Templates"
■ Section 19.4, "Using Declarative Components"
■ Section 19.5, "Adding Resources to Pages"
19.1 Introduction to Reusable Content
As you build JSF pages for your application, some pages may become complex and
long, making editing complicated and tedious. Some pages may always contain a
group of components arranged in a very specific layout, while other pages may always
use a specific group of components in multiple parts of the page. And at times, you
may want to share some parts of a page or entire pages with other developers.
Whatever the case is, when something changes in the UI, you have to replicate your
changes in many places and pages. Building and maintaining all those pages, and
making sure that some sets or all are consistent in structure and layout can become
increasingly inefficient.
Instead of using individual UI components to build pages, you can use page building
blocks to build parts of a page or entire pages. The building blocks contain the
frequently or commonly used UI components that create the reusable content for use
in one or more pages of an application. Depending on your application, you can use
just one type of building block, or all types in one or more pages. And you can share
some building blocks across applications. When you modify the building blocks, the
JSF pages that use the reusable content are automatically updated as well. Thus, by
creating and using reusable content in your application, you can build web user
interfaces that are always consistent in structure and layout, and an application that is
scalable and extensible.
ADF Faces provides the following types of reusable building blocks:
■ Page fragments: Page fragments allow you to create parts of a page. A JSF page
can be made up of one or more page fragments. For example, a large JSF page can
be broken up into several smaller page fragments for easier maintenance. For

3 Using ADF Faces Architecture (ofm-wui-dg)

3 Using ADF Faces Architecture

This chapter outlines the major features of the ADF Faces client-side architecture.

This chapter includes the following sections:

■ Section 3.1, "Introduction to Using ADF Faces Architecture"

■ Section 3.2, "Listening for Client Events"

■ Section 3.3, "Adding JavaScript to a Page"

■ Section 3.4, "Instantiating Client-Side Components"

■ Section 3.5, "Locating a Client Component on a Page"

■ Section 3.6, "Determining the User’s Current Location"

■ Section 3.7, "Accessing Component Properties on the Client"

■ Section 3.8, "Using Bonus Attributes for Client-Side Components"

■ Section 3.9, "Understanding Rendering and Visibility"

3.1 Introduction to Using ADF Faces Architecture

The ADF Faces rich client framework (RCF) provides many of the features you need to

create AJAX-type functionality in your web application, all built into the framework. A

key aspect of the RCF is the sparsely populated client-side component model. Client

components exist only when they are required, either due to having a

clientListener handler registered on them, or because the page developer needs

to interact with a component on the client side and has specifically configured the

client component to be available.

The main reason client components exist is to provide an API contract for the

framework and for developers. You can think of a client-side component as a simple

property container with support for event handling. Because client components exist

only to store state and provide an API, they have no direct interaction with the DOM

(document object model) whatsoever. All DOM interaction goes through an

intermediary called the peer. Most of the inner workings of the framework are hidden

from you. Using JDeveloper in conjunction with ADF Faces, you can use many of the

architectural features declaratively, without having to create any code.

For example, because RCF does not create client components for every server-side

component, there may be cases where you need a client version of a component

instance. Section 3.4, "Instantiating Client-Side Components," explains how to do this

declaratively. You use the Property Inspector in JDeveloper to set properties that

determine whether a component should be rendered at all, or simply be made not

visible, as described in Section 3.9, "Understanding Rendering and Visibility."

Other functionality may require you to use the ADF Faces JavaScript API. For

example, Section 3.5, "Locating a Client Component on a Page," explains how to use

the API to locate a specific client-side component, and Section 3.7, "Accessing

Component Properties on the Client," documents how to access specific properties.

3.2 Listening for Client Events

In a traditional JSF application, if you want to process events on the client, you must

listen to DOM-level events. However, these events are not delivered in a portable

manner. The ADF Faces client-side event model is similar to the JSF events model, but

implemented on the client. The client-side event model abstracts from the DOM,

providing a component-level event model and lifecycle, which executes independently

of the server. Consequently, you do not need to listen for click events on buttons.

You can instead listen for AdfActionEvent events, which can be caused by key or

mouse events.

Events sent by clients are all subclasses of the AdfBaseEvent class. Each client event

has a source, which is the component that triggered the event. Events also have a type

(for example, action or dialog), used to determine which listeners are interested in

the event. You register a client listener on the component using the

af:clientListener tag.

For example, suppose you have a button that, when clicked, causes a "Hello World"

alert to be displayed. You would first register a listener with the button that will

invoke an event handler, as shown in Example 3–1.

Example 3–1 Registering a Client Listener

<af:commandButton text="Say Hello">

<af:clientListener method="sayHello" type="action"/>

</af:commandButton>

Because the button has a registered client listener, the

framework will automatically create a client version of the

component.

Next, implement the handler in a JavaScript function, as shown in Example 3–2.

Example 3–2 JavaScript Event Handler

function sayHello(event)

{

alert("Hello, world!")

}

When the button is clicked, because there is a client version of the component, the

AdfAction client event is invoked. Because a clientListener tag is configured to

listen for the AdfAction event, it causes the sayHello function to execute. For more

information about client-side events

3.3 Adding JavaScript to a Page

You can either add inline JavaScript directly to a page or you can import JavaScript

libraries into a page. When you import libraries, you reduce the page content size, the

libraries can be shared across pages, and they can be cached by the browser. You

should import JavaScript libraries whenever possible. Use inline JavaScript only for

cases where a small, page-specific script is needed.

Tip:

including JavaScript only in the pages that need it

will result in better performance because those pages that do not need

it will not have to load it, as they would if the JavaScript were

included in a template. However, if you find that most of your pages

use the same JavaScript code, you may want to consider including the

script or the tag to import the library in a template.

Note,

however, that if a JavaScript code library becomes too big, you

should consider splitting it into meaningful pieces and include only

the pieces needed by the page (and not in a template). This approach

will provide improved performance, because the browser cache will

be used and the HTML content of the page will be smaller

3.3.1 How to Use Inline JavaScript

Create and use inline JavaScript in the same way you would in any JSF application.

Once the JavaScript is on the page, use a clientListener tag to invoke it.

To use inline JavaScript:

1. Add the MyFaces Trinidad tag library to the root element of the page by adding

the code shown in bold in Example 3–3.

Example 3–3 MyFaces Trinidad Tag Library on a Page

<jsp:root

xmlns:jsp="http://java.sun.com/JSP/Page"version="2.1"

xmlns:f="http://java.sun.com/jsf/core"

xmlns:h="http://java.sun.com/jsf/html"

xmlns:af="http://xmlns.oracle.com/adf/faces/rich"

xmlns:trh="http://myfaces.apache.org/trinidad/html">

2. Create the JavaScript on the page.

For example, the sayHello function shown in Example 3–2 might be included in

a JSF page as shown in Example 3–4.

Example 3–4 Inline JavaScript

<af:resource>

function sayHello()

{

alert("Hello, world!")

}

</af:resource>

3. In the Structure window, right-click the component that will invoke the JavaScript,

and choose Insert inside component > ADF Faces > Client Listener.

4. In the Insert Client Listener dialog, in the Method field, enter the JavaScript

function name. In the Type field, select the event type that should invoke the

function.

3.3.2 How to Import JavaScript Libraries

Use the af:resource tag to access a JavaScript library from a page. This tag should

appear inside the document tag’s metaContainer facet.

To access a JavaScript library from a page:

1. Below the document tag, add the code shown in bold in Example 3–5 and replace

/mySourceDirectory with the relative path to the directory that holds the

JavaScript library.

Example 3–5 Accessing a JavaScript Library

<af:document>

<f:facet name="metaContainer">

<af:resource source="/mySourceDirectory"/>

</facet>

<af:form></af:form>

</af:document>

2. In the Structure window, right-click the component that will invoke the JavaScript,

and choose Insert inside component > ADF Faces > Client Listener.

3. In the Insert Client Listener dialog, in the Method field, enter the fully qualified

name of the function. For example, if the sayHello function was in the

MyScripts library, you would enter MyScripts.sayHello. In the Type field,

select the event type that should invoke the function.

3.3.3 What You May Need to Know About Accessing Client Event Sources

Often when your JavaScript needs to access a client, it is within the context of a listener

and must access the event’s source component. Use the getSource() method to get

the client component. Example 3–6 shows the sayHello function accessing the source

client component in order to display its name.

Example 3–6 Accessing a Client Event Source

function sayHello(actionEvent)

{

var component=actionEvent.getSource();

//Get the ID for the component

var id=component.getId

alert("Hello from "+id);

}

For more information about accessing client event sources, see Section 5.3, "Using

JavaScript for ADF Faces Client Events." For more information about accessing

client-side properties, see Section 3.7, "Accessing Component Properties on the Client."

For a complete description of how client events are handled at runtime, see

Section 5.3.6, "What Happens at Runtime: How Client-Side Events Work."

3.4 Instantiating Client-Side Components

The RCF does not make any guarantees about which components will have

corresponding client-side component instances by default. You will usually interact

with client-side components by registering a clientListener handler. When a

component has a registered clientListener handler, it will automatically have

client-side representation. If you have to access another component on the client, then

explicitly configure that component to be available on the client by setting the

clientComponent attribute to true.

When you set the clientComponent attribute to true, the framework creates an

instance of an AdfUIComponent class for the component. This class provides the API

that you can work with on the client side and also provides basic property accessor

methods (for example, getProperty() and setProperty()), event listener

registration, and event delivery-related APIs. The framework also provides

renderer-specific subclasses (for example, AdfRichOutputText) which expose

property-specific accessor methods (for example, getText() and setText()). These

accessor methods are simply wrappers around the AdfUIComponent class’s

getProperty() and setProperty() methods and are provided for coding

convenience.

For example, suppose you have an outputText component on the page that will get

its value (and therefore the text to display) from the sayHello function. That function

must be able to access the outputText component in order to set its value. For this to

work, there must be a client-side version of the outputText component. Example 3–7

shows the JSF page code. Note that the outputText component has an id value and

the clientComponent attribute is set to true. Also, note there is no value in the

example, because that value will be set by the JavaScript.

Example 3–7 Adding a Component

<af:commandButton text="Say Hello">

<af:clientListener method="sayHello" type="action"/>

</af:commandButton>

<af:outputText id="greeting" value="" clientComponent="true">

Because the outputText component will now have client-side representation, the

JavaScript will be able to locate and work with it.

3.5 Locating a Client Component on a Page

When you need to find a client component that is not the source of an event, you can

use the AdfUIComponent.findComponent(expr) method. This method is similar

to the JSF UIComponent.findComponent() method, which searches for and returns

the UIComponent object with an ID that matches the specified search expression. The

AdfUIComponent.findComponent(expr) method simply works on the client

instead of the server.

Example 3–8 shows the sayHello function finding the outputText component

using the component’s ID.

Example 3–8 Finding a Client Component Using findComponent()

function sayHello(actionEvent)

{

var component=actionEvent.getSource();

//Find the client component for the "greeting" af:outputText

var greetingComponent=component.findComponent("greeting");

//Set the value for the outputText component

greetingComponent.setValue("Hello World")

}

Instead of using the AdfUIComponent.findComponent(expr) method, you can

use the AdfPage.PAGE.findComponentByAbsoluteId(absolute expr)

method when you know the absolute identifier for the component, but you don't have

a component instance to call AdfUIComponent.findComponent(expr) on.

AdfPage.PAGE is a global object that provides a static reference to the page's context

object. However, if the component you are finding is within a naming container, then

you must use AdfUIComponent.findComponent. For more information, see

Section 3.5.1, "What You May Need to Know About Finding Components in Naming

Containers."

Note:

There is also a confusingly named

AdfPage.PAGE.findComponent(clientId) method, however

this function uses implementation-specific identifiers that can change

between releases and should not be used by page authors.

3.5.1 What You May Need to Know About Finding Components in Naming Containers

If the component you need to find is within a component that is a naming container

(such as pageTemplate, subform, table, and tree), then instead of using the

AdfPage.PAGE.findComponentByAbsoluteId(absolute expr) method, use

the AdfUIComponent.findComponent(expr) method. The expression can be

either absolute or relative.

Tip:

You can determine whether or not a component is a naming

container by reviewing the component tag documentation. The tag

documentation states whether a component is a naming container

Absolute expressions use the fully qualified JSF client ID (meaning, prefixed with the

IDs of all NamingContainer components that contain the component) with a leading

NamingContainer.SEPARATOR_CHAR character, for example:

":" + (namingContainersToJumpUp * ":") + some ending portion of the

clientIdOfComponentToFind

For example, to find a table whose ID is t1 that is within a panel collection component

whose ID is pc1 contained in a region whose ID is r1 on page that uses the

myTemplate template, you might use the following:

:myTemplate:r1:pc1:t1

Alternatively, if both the components (the one doing the search and the one being

searched for) share the same NamingContainer component somewhere in the

hierarchy, you can use a relative path to perform a search relative to the component

doing the search. A relative path has multiple leading

NamingContainer.SEPARATOR_CHAR characters, for example:

":" + clientIdOfComponentToFind

In the preceding example, if the component doing the searching is also in the same

region as the table, you might use the following:

::somePanelCollection:someTable

Tip:

Think of a naming container as a folder and the clientId as a

file path. In terms of folders and files, you use two sequential periods

and a slash (../) to move up in the hierarchy to another folder.

This is the same thing that the multiple colon (:) characters do in the

findComponent() expression. A single leading colon (:) means

that the file path is absolute from the root of the file structure. If there

are multiple leading colon (:) characters at the beginning of the

expression, then the first one is ignored and the others are counted,

one set of periods and a slash (../) per colon (:) character.

When deciding whether to use an absolute or relative path, keep the following in

mind:

■ If you know that the component you are trying to find will always be in the same

naming container, then use an absolute path.

■ If you know that the component performing the search and the component you

are trying to find will always be in the same relative location, then use a relative

path.

There are no getChildren() or getFacet() functions on the client. Instead, the

AdfUIComponent.visitChildren() function is provided to visit all children

components or facets (that is all descendents). See the ADF Faces JavaScript

documentation for more information.

3.6 Determining the User’s Current Location

ADF Faces provides JavaScript APIs that return the current contextual page

information, in response to an event. The AdfPage.prototype.getViewId()

function returns the identifier for the currently displayed view. This ID is set when

either a full page render or a partial page navigation occurs. The

AdfPage.prototype.getComponentsByType(componentType) function

returns an array of component instances that match the given component type.

For example, say your application contains a page with tabs, and each tab is made up

of a number of regions. Each region could contain other nested regions as well. You

can use the APIs to return a String identifier that is a combination of the viewId of the

entire page and the viewIds of the fragments displayed in each of the regions

currently rendered on the page, as shown in Example 3–9.

3.6.1 How to Determine the User’s Current Location

In order to retrieve the viewID property of the region component on the client, the

user activity monitoring feature needs to be enabled by setting a parameter in the

web.xml file. You then create JavaScript code that builds a String representation of the

viewIds that make up the current page.

To determine a context identifier:

1. Double-click the web.xml file.

2. In the source editor, set the oracle.adf.view.faces.context.ENABLE_

ADF_EXECUTION_CONTEXT_PROVIDER to true.

This parameter notifies ADF Faces that the ExecutionContextProvider

service provider is enabled. This service monitors and aggregates user activity

information for the client-initiated requests.

3. Set oracle.adf.view.rich.automation.ENABLED to true.

This parameter ensures that component IDs are set for all components. For more

information, see Section A.2.3.10, "Test Automation."

4. Create the JavaScript to build the context identifier (for more information about

adding JavaScript, see Section 3.3, "Adding JavaScript to a Page").

Example 3–9 shows JavaScript used to get the current view ID for a region.

Example 3–9 JavaScript to Retrieve viewIds

/**

* Returns a String identifier comprising the page viewId and viewIds

* of the fragments displayed in each of the displayed regions

*/

TestLibrary.prototype.getCurrentPageInfo = function()

{

var pageIdentifier = null;

var page = AdfPage.PAGE;

if (page)

{

// get the viewId of the page

var viewId = page.getViewId();

// get all region components currently displayed on the page

var regionComponents = page.getComponentsByType("oracle.adf.RichRegion");

var regionViewIds = new Array();

for (var index = 0; index < regionComponents.length; index++)

//ToDo

3.7 Accessing Component Properties on the Client

3.7.1 How to Set Property Values on the Client

3.7.2 How to Unsecure the disabled Property

3.9 Understanding Rendering and Visibility