11.4 Enabling Partial Page Rendering

ADF Faces components use partial page rendering (PPR), which allows small areas of a page to be refreshed without the need to redraw the entire page. PPR is currently supported on the following browsers:

Internet Explorer 5.5 and above (Windows)
Mozilla 1.0/Netscape 7.0

On all other platforms, ADF Faces automatically uses full page rendering You don't need to disable PPR or write code to support both cases.

Most of the time you don't have to do anything to enable PPR because ADF Faces components have built-in support for PPR. For example, in the SRSearch.jspx page, the Results section of the page uses a showOneTab component with two showDetailItem components to let the user display either a summary view or detail view of the search results. Figure 11-11 shows the Results section with the Summary View selected. When the user clicks Detail View, only the portion of the page that is below the Results title will refresh.

Figure 11-11 Search Page (SRSearch.jspx) with the Summary Result View Selected

Search page showing closed service requests summary table.

At times you want to explicitly refresh parts of a page yourself. For example, you may want an output component to display what a user has chosen or entered in an input component, or you may want a command link or button to update another component. Three main component attributes can be used to enable partial page rendering:

autoSubmit: When the autoSubmit attribute of an input component (such as inputText and selectOneChoice) or a table select component (such as tableSelectOne) is set to true, and an appropriate action takes place (such as a value change), the component automatically submits the form it is enclosed in. For PPR, you might use this in conjunction with a listener attribute bound to a method that performs some logic when an event based on the submit is launched.
partialSubmit: When the partialSubmit attribute of a command component is set to true, the page partially submits when the button or link is clicked. You might use this in conjunction with an actionListener method that performs some logic when the button or link is clicked.
partialTriggers: All rendered components support the partialTriggers attribute. The value of this attribute is one or more IDs of other trigger components. When those trigger components are updated (for example through an automatic submit or a partial submit), the target component is also updated.

11.4.1 How to Enable PPR

The SREdit.jspx page of the SRDemo application uses partial page submits and partial triggers to support PPR.

Figure 11-12 shows the SREdit.jspx page with an unassigned service request. When the user clicks the flashlight icon (which is a commandLink component with an objectImage component), a popup dialog displays to allow the user to search and select a name. After selecting a name, the popup dialog closes and the Assigned to display-only fields are refreshed with the selected name; other parts of the edit page are not refreshed.

Figure 11-12 Edit Service Request Page (SREdit.jspx) with an Unassigned Request

To enable a command component to partially refresh another component:

On the trigger command component, set the id attribute to a unique value, and set the partialSubmit attribute to true.
On the target component that you want to partially refresh when the trigger command component is activated, set the partialTriggers attribute to the id of the command component.

Tip:

A component's unique 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.

Example 11-36 shows the code snippets for the command and read-only input components used in the SREdit.jspx page to illustrate PPR.

Example 11-36 Code for Enabling Partial Page Rendering Through a Partial Submit

<af:panelLabelAndMessage label="#{res['sredit.assignedTo.label']}">
  <af:panelHorizontal>
    <af:outputText value="#{bindings.assignedToFirstName.inputValue}"
                   partialTriggers="staffLOVLink"/>
    <af:outputText value="#{bindings.assignedToLastName.inputValue}"
                  partialTriggers="staffLOVLink"/>
    <af:commandLink id="staffLOVLink" action="dialog:StaffSearch"
                    useWindow="true" immediate="true"
                    partialSubmit="true"
                    returnListener="#{backing_SREdit.handleStaffLOVReturn}"
                    partialTriggers="status"
                    disabled="#{bindings.ServiceRequeststatus.inputValue==2}">
      <af:objectImage height="24" width="24"
                      source="/images/searchicon_enabled.gif"/>
    </af:commandLink>
    <f:facet name="separator">
      <af:objectSpacer width="4" height="10"/>
    </f:facet>
  </af:panelHorizontal>
</af:panelLabelAndMessage>

Tip:

The partialTriggers attribute on a target component can contain the id of one or more trigger components. Use spaces to separate multiple ids.

11.4.2 What Happens at Runtime

ADF Faces command buttons and links can generate partial events. The partialSubmit attribute on commandButton or commandLink determines whether a partial page submit is used to perform an action or not. When partialSubmit is true, ADF Faces performs the action through a partial page submit. Thus you can use a command button or link to update a portion of a page, without having to redraw the entire page upon a submit. By default the value of partialSubmit is false, which means full page rendering is used in response to a partial event. Full page rendering is also automatically used when partial page rendering is not supported in the client browser or platform or when navigating to another page.

In the example, the partialTriggers attributes on the Assigned to display-only outputText components are set to the id of the commandLink component. When the commandLink component fires a partial event, the output components (which are listening for partial events from commandLink) know to refresh their values via partial page rendering.

11.4.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 action. Hence, you should place the target components after the component that fires the partial request; otherwise the screen reader would not read the updated targets.