Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

7 Rerendering Partial Page Content

This chapter describes how to use the partial page refresh features provided with ADF Faces components to refresh areas of a page without refreshing the whole page.

This chapter includes the following sections:

7.1 Introduction to Partial Page Rendering

AJAX (Asynchronous JavaScript and XML) is a web development technique for creating interactive web applications, where web pages appear more responsive by exchanging small amounts of data with the server behind the scenes, without the whole web page being refreshed. The effect is to improve a web page's interactivity, speed, and usability.

With ADF Faces, the feature that delivers the AJAX partial page refresh behavior is called partial page rendering (PPR). PPR allows only certain components on a page to be rerendered without the need to refresh the entire page. For example, an output component can display what a user has chosen or entered in an input component, or a command link or button can cause another component on the page to be rerendered, without the whole page refreshing.

In order for PPR to work, boundaries must be set on the page that allow the lifecycle to run just on components within the boundary. In order to determine the boundary, the framework must be notified of the root component to process. The root component can be identified in two ways:

In addition to built-in PPR functionality, you can configure components to use cross-component rendering, which allows you to set up dependencies so that one component acts as a trigger and another component as the listener. When an event occurs on the trigger component, the lifecycle is run only on listener components and children components to the listener, and only the listener components and their children are rerendered. Cross-component rendering can be implemented declaratively in JDeveloper. However, by default, all events from a trigger component will cause PPR, (although some components, such as table, trigger partial targets on only a subset of their events). For these cases where you need strict control over the event that launches PPR, or for cases where you want to use some logic to determine the target, you can implement PPR programatically.

Tip:

If your application uses the Fusion technology stack, you can enable the Auto-PPR feature on any page. This causes any components whose values change as a result of backend business logic to be automatically rerendered. For more information, see the "Understanding the Fusion Page Lifecycle " chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Additionally, ADF Faces applications can use PPR for navigation. In standard JSF applications, the navigation from one page to the next requires the new page to be rendered. When using AJAX-like components, this can cause overhead because of the time needed to download the different JavaScript libraries and style sheets. To avoid this costly overhead, the ADF Faces architecture can optionally simulate full-page transitions while actually remaining on a single page, thereby avoiding the need to reload JavaScript code and skin styles.

Note:

The browser must have JavaScript enabled in order for PPR to work.

7.2 Enabling Partial Page Rendering Declaratively

Using the simplest form of cross-component rendering, one component, referred to as the target component, is rerendered when any event occurs on another component, referred to as the trigger component.

For example, as shown in Figure 7-1, the File Explorer application contains table that shows the search results in the Search panel. This table (and only this table) is rerendered when the search button is activated. The search button is configured to be the trigger and the table is configured to be the target.

Figure 7-1 The Search Button Causes Results Table to Rerender

Search button causes table to rerender

Note:

In some cases, you may want a component to be rerendered only when a particular event is fired, not for every event associated with the trigger component, or you may want some logic to determine whether a component is to be rerendered. In these cases, you can programatically enable PPR. For more information, see Section 7.3, "Enabling Partial Page Rendering Programmatically"

Trigger components must inform the framework that a PPR request has occurred. On command components, this is achieved by setting the partialSubmit attribute to true. Doing this causes the command component to fire a partial page request each time it is clicked.

For example, say a page includes an inputText component, a commandButton component, and an outputText component. When the user enters a value for the inputText component, and then clicks the commandButton component, the input value is reflected in the outputText component. You would set the partialSubmit attribute to true on the commandButton component.

However, components other than command components can trigger PPR. ADF Faces input and select components have the ability to trigger partial page requests automatically whenever their values change. To make use of this functionality, use the autoSubmit attribute of the input or select component so that as soon as a value is entered, a submit occurs, which in turn causes a valueChangeEvent event to occur. It is this event that notifies the framework to execute a PPR, as long as a target component is set. In the previous example, you could delete the commandButton component and instead set the inputText component's autoSubmit attribute to true. Each time the value changes, a PPR request will be fired.

Tip:

The autoSubmit attribute on an input component and the partialSubmit attribute on a command component are not the same thing. When partialSubmit is set to true, then only the components that have values for their partialTriggers attribute will be processed through the lifecycle. The autoSubmit attribute is used by input and select components to tell the framework to automatically do a form submit whenever the value changes. However, when a form is submitted and the autoSubmit attribute is set to true, a valueChangeEvent event is invoked, and the lifecycle runs only on the components marked as root components for that event, and their children. For more information, see Section 4.3, "Using the Optimized Lifecycle".

Once PPR is triggered, any component configured to be a target will be rerendered. You configure a component to be a target by setting the partialTriggers attribute to the relative ID of the trigger component. For information about relative IDs, see Section 3.5, "Locating a Client Component on a Page".

In the example, to update the outputText in response to changes to the inputText component, you would set its partialTriggers attribute to the inputText component's relative ID.

Note:

Certain events on components trigger PPR by default, for example the disclosure event on the showDetail component and the sort event on a table. This means that any component configured to be a target by having its partialTriggers attribute set to that component's ID will rerender when these types of events occur.

7.2.1 How to Enable Partial Page Rendering

For a component to be rerendered based on an event caused by another component, it must declare which other components are the triggers.

To enable a component to rerender another component:

  1. In the Structure window, select the trigger component (that is, the component whose action will cause the PPR):

    • Expand the Common section of the Property Inspector and set the id attribute to a unique value within that component's naming container. If the component is not within a naming container, then the ID must be unique to the page. For more information about naming containers, see Section 3.5, "Locating a Client Component on a Page".

      An ID is needed so that the partialTriggers attribute of the listening component can identify the trigger component.

      Tip:

      A component's ID must be a valid XML name, that is, you cannot use leading numeric values or spaces in the ID. JSF also does not permit colons ( : ) in the ID.
    • If the trigger component is a command component, expand the Behavior section of the Property Inspector, and set the partialSubmit attribute to true.

    • If the trigger component is an input or select component in a form and you want the value to be submitted, expand the Behavior section of the Property Inspector, and set the autoSubmit attribute of the component to true.

      Note:

      Set the autoSubmit attribute to true only if you want the component to submit its value. If you do not want to submit the value, then some other logic must cause the component to issue a ValueChangeEvent event. That event will cause PPR by default and any component that has the trigger component as its value for the partialTriggers attribute will be rerendered.
  2. In the Structure window, select the target component that you want to rerender when a PPR-triggering event takes place.

  3. Expand the Behavior section of the Property Inspector, click the dropdown menu for the partialTriggers attribute and choose Edit.

  4. In the Edit Property dialog, shuttle the trigger component to the Selected panel and click OK. If the trigger component is within a naming container, JDeveloper automatically creates the relative path for you.

Tip:

The selectBooleanRadio components behave like a single component with partial page rendering, however they are in fact, multiple components. Therefore, if you want other components (such as inputText components) to change based on selecting a different selectBooleanRadio component in a group, you must group them within a parent component, and set the partialTriggers attribute of the parent component to point to all of the SelectBooleanRadio components.

Example 7-1 shows a commandLink component configured to execute PPR.

Example 7-1 Code for Enabling Partial Page Rendering Through a Partial Submit

<af:commandLink id="deleteFromCart" partialSubmit="true"
                actionListener="#{homeBean...}">

Example 7-2 shows an outputText component that will be rerendered when the command link with ID deleteFromCart in Example 7-1 is clicked.

Example 7-2 Code for Partial Refresh Triggered by Another Component

<af:outputText id="estimatedTotalInPopup"
               partialTriggers="deleteFromCart"
               value="#{shoppingCartBean...}"/>

Tip:

You can use PPR to avoid components from being validated on a page. For more information, see Section 4.3, "Using the Optimized Lifecycle".

7.2.2 What You May Need to Know About Using the Browser Back Button

In an ADF Faces application, because some components use PPR (either implicitly or because they have been configured to listen for a partial trigger), what happens when a user clicks the browser's Back button is slightly different than in an application that uses simple JSF components.

Typically, when the user clicks the browser's back button, the browser returns the page to the state of the DOM (document object model) as it was when last rendered, but the state of the JavaScript is as it was when the user first entered the page.

For example, say a user visited PageA. After interacting with components on the page, say a PPR event took place using JavaScript. Let's call this new version of the page PageA1. Next, say the user navigates to PageB, then clicks the browser Back button to return to PageA. The user will be shown the DOM as it was on PageA1, but the JavaScript will not have run, and therefore parts of the page will be as it was for PageA. This might mean that changes to the page will be lost. While refreshing the page will run the JavaScript and so return the user to the state it was in PageA1, the ADF Faces framework provides built-in support so that the refresh is not needed.

7.2.3 What You May Need to Know About PPR and Screen Readers

Screen readers do not reread the full page in a partial page request. PPR causes the screen reader to read the page starting from the component that fired the partial page request. Hence, you should place the target components after the component that triggers the partial request; otherwise the screen reader would not read the updated target components.

7.3 Enabling Partial Page Rendering Programmatically

For components such as tables that have many associated events, PPR will happen any time any event is triggered, causing any component with the table as a partial trigger to be rerendered each time. If you want the target to be rerendered only for certain events, or if you want a target to be rerendered based on some other logic, you can enable partial page rendering programmatically.

The addPartialTarget() method allows you to add a component as a partial target for an event, so that when that event is triggered, the partial target component is rerendered. Using this method associates the component you want to have rerendered with the event that is to trigger the rerendering.

For example, the File Explorer application contains the NavigatorManager.refresh() method. When invoked, the navigator accordion is rerendered.

Example 7-3 Rerendering Using Partial Targets

public void refresh()
  {
    for (BaseNavigatorView nav: getNavigators())
    {
      nav.refresh();
    }
    
    AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
      adfFacesContext.addPartialTarget(_navigatorAccordion);
  }

In the case where you want the rerender to occur based on just one event of a component, you could have a listener for that event implement the addPartialTrigger() method.

7.4 Partial Page Navigation

Instead of performing a full page transition in the traditional way, navigation can be triggered through a partial page rendering request. The actual navigation to the new page occurs as usual on the server. However, rather than including the complete page contents in the response, only the visual contents of the page are included (in other words, the <html>, <head>, and <body> elements are omitted). The visual contents are inserted into the DOM on the client without leaving the current page. This substitution can happen because the ADF Faces document component renders a <div> element inside the <body> element. This <div> element surrounds all other content in the page. During PPR navigation, the contents of the original <div> element are simply replaced with the next page's <div> content.

In order to keep track of location (for example, for bookmarking purposes, or when a refresh occurs), the framework makes use of the hash portion of the URL. This portion of the URL contains the actual page being displayed in the browser.

7.4.1 How to Enable PPR Navigation

The type of navigation used by an application is set in the web.xml file. By default, standard navigation is used. Add a context parameter in order to turn on PPR navigation.

To enable PPR navigation:

  1. Open the web.xml file. By default, this is located in the WEB-INF directory.

  2. In the overview editor, expand the Context Initialization Parameters section and click the Add icon to add the new parameter.

  3. Enter oracle.adf.view.rich.pprNavigation.OPTIONS as the Name.

  4. For Value, enter one of the following:

    • on: PPR navigation is turned on for the application.

    • off: PPR navigation is turned off for the application.

    • onWithForcePPR: When an action on a command component results in navigation, the action will always be delivered using PPR, as if the component had the partialSubmit attribute set to true (for more information about partialSubmit, see Section 5.1.1, "Events and Partial Page Rendering"). Therefore, if the component already has partialSubmit set to true, the framework does nothing. Otherwise, the entire document is refreshed to ensure that old page refresh behavior is preserved. The entire document is also refreshed if the action component does not contain navigation.

  5. If you set the context parameter to on, set the partialSubmit attribute to true for any command components involved in navigation.

7.4.2 What You May Need to Know About PPR Navigation

Before using PPR navigation, you should be aware of the following:

  • When using PPR navigation, all pages involved in navigation must use the same style sheets.

  • Because PPR navigation makes use of the hash portion of the URL, you cannot use the hash portion for navigation to anchors within the page.

  • The page being navigated to does not have to use the same JavaScript library as the previous page. However, the previous page's JavaScript will not be unloaded.