Unlike standard JSF events, ADF Faces events support Ajax-style partial postbacks to enable partial page rendering (PPR). Instead of full page rendering, ADF Faces events and components can trigger partial page rendering, that is, only portions of a page refresh upon request and the lifecycle is run only on that portion.

Certain components are considered event root components. Event root components determine boundaries on the page, and so allow the lifecycle to run just on components within that boundary (for information about this aspect of the lifecycle, see Using the Optimized Lifecycle). When an event occurs within an event root, only those components that are children to the root are refreshed on the page.

An example of an event root component is a popup. When an event happens within a popup, only the popup and its children are rerenderd, and not the whole page. Another example is the panelCollection component that surrounds a table and provides among other things, a toolbar. Action events triggered by a button on the toolbar will cause the lifecycle to be run only on the child components of the panelCollection component.

The following components are considered event root components:

• popup

• region

• panelCollection

• calendar

• editableValueHolder components (such as inputText)

Additionally, certain events indicate a specific component as an event root component. For example, the disclosure event sent when a expanding or collapsing a showDetail component (see Displaying and Hiding Contents Dynamically), indicates that the showDetail component is a root. The lifecycle is run only on the showDetail component (and any child components or other components that point to this as a trigger), and only they are rerendered when it is expanded or collapsed. For information about components and their associated events, see Event and Even Root Components.

In addition to server-side action and value change events, ADF Faces components also invoke client-side action and value change events, and other kinds of server and client events. Some events are generated by both server and client components (for example, selection events); some events are generated by server components only (for example, launch events); and some events are generated by client components only (for example, load events).

By default, most client events are propagated to the server. Changes to the component state are automatically synchronized back to the server to ensure consistency of state, and events are delivered, when necessary, to the server for further processing. However, you can configure your event so that it does not propagate.

In addition, any time you register a client-side event listener on the server-side Java component, the ADF Faces framework assumes that you require a JavaScript component, so a client-side component is created.

Client-side JavaScript events can come from several sources: they can be derived automatically from DOM events, from property change events, or they can be manually created during the processing of other events.

1. In a managed bean (or the backing bean for the page that will use the event listener), create a public method that accepts the event (as the event type) as the only parameter and returns void. The following example shows the code for the tableSelectFileItem handler. (For information about creating and using managed beans, see Creating and Using Managed Beans.)

     public void tableSelectFileItem(SelectionEvent selectionEvent)
     {
       FileItem data = (FileItem)this.getContentTable().getSelectedRowData();
       setSelectedFileItem(data);
     }
   

   Tip:

   If the event listener code is likely to be used by more than one page in your application, consider creating an event listener implementation class that all pages can access. All server event listener class implementations must override a processEvent() method, where Event is the event type.

   For example, the LaunchListener event listener accepts an instance of LaunchEvent as the single argument. In an implementation, you must override the event processing method, as shown in the following method signature:

   public void processLaunch (LaunchEvent evt) 
   {
     // your code here
   }

2. To register an event listener method on a component, in the Structure window, select the component that will invoke the event. In the Properties window, use the dropdown menu next to the event listener property, and choose Edit.
3. Use the Edit Property dialog to select the managed bean and method created in Step 1.

   The following example shows sample code for registering a selection event listener method on a table component.

   <af:table id="folderTable" var="file"
   . . . 
             rowSelection="single"
             selectionListener="#{explorer.tableContentView.tableSelectFileItem}"
   . . .
   </af:table>

Event processing in general is taken from the browser's native event loop. The page receives all DOM events that bubble up to the document, and hands them to the peer associated with that piece of DOM. The peer is responsible for creating a JavaScript event object that wraps that DOM event, returning it to the page, which queues the event (for information about peers and the ADF Faces architecture, see Using ADF Faces Client-Side Architecture ).

The event queue on the page most commonly empties at the end of the browser's event loop once each DOM event has been processed by the page (typically, resulting in a component event being queued). However, because it is possible for events to be queued independently of any user input (for example, poll components firing their poll event when a timer is invoked), queueing an event also starts a timer that will force the event queue to empty even if no user input occurs.

The event queue is a First-In-First-Out queue. For the event queue to empty, the page takes each event object and delivers it to a broadcast() function on the event source. This loop continues until the queue is empty. It is completely legitimate (and common) for broadcasting an event to indirectly lead to queueing a new, derived event. That derived event will be broadcast in the same loop.

When an event is broadcast to a component, the component does the following:

1. Delivers the event to the peer's DispatchComponentEvent method.

2. Delivers the event to any listeners registered for that event type.

3. Checks if the event should be bubbled, and if so initiates bubbling. Most events do bubble. Exceptions include property change events (which are not queued, and do not participate in this process at all) and, for efficiency, mouse move events.

   While an event is bubbling, it is delivered to the AdfUIComponent HandleBubbledEvent function, which offers up the event to the peer's DispatchComponentEvent function. Note that client event listeners do not receive the event, only the peers do.

   Event bubbling can be blocked by calling an event's stopBubbling() function, after which the isBubblingStopped() function will return true, and bubbling will not continue. As with cancelling, you cannot undo this call.

   Note:

   Canceling an event does not stop bubbling. If you want to both cancel an event and stop it from bubbling, you must call both functions.

4. If none of the prior work has canceled the event, calls the AdfUIComponent.HandleEvent method, which adds the event to the server event queue, if the event requests it.

Several components in ADF Faces are NamingContainer components, such as pageTemplate, subform, table, and tree. When working with client-side API and events in pages that contain NamingContainer components, you should use the findComponent() method on the source component.

For example, because all components in any page within the File Explorer application eventually reside inside a pageTemplate component, any JavaScript function must use the getSource() and findComponent() methods, as shown in the following example. The getSource() method accesses the AdfUIComponent class, which can then be used to find the component.

function showPopup(event)
{
  event.cancel();
  var source = event.getSource();
  var popup = source.findComponent("popup");
  popup.show({align:"after_end", alignId:"button"});
}

When you use the findComponent() method, the search starts locally at the component where the method is invoked. For information about working with naming containers, see Locating a Client Component on a Page.

1. Create the JavaScript that will handle the custom event using the AdfCustomEvent.queue() method to provide the event source, custom event type, and the parameters to send to the server.

   For example, the JavaScript used to cause the pressing of the Enter key to invoke the search functionality uses the AdfCustomEvent.queue method that takes the event source, the string enterPressedOnSearch as the custom event type, a null parameter map, and False for the immediate parameter, as shown in he following example.

   Explorer.searchNameHandleKeyPress = function (event)
   {
     if (event.getKeyCode()==AdfKeyStroke.ENTER_KEY)
     {
       var source = event.getSource();
       AdfCustomEvent.queue(source,
                            "enterPressedOnSearch", 
                            {}, 
                            false);
     } 
   }
   

2. Create the server listener method on a managed bean. This method must be public and take an oracle.adf.view.rich.render.ClientEvent object and return a void type. The following example shows the code used in the SearchNavigatorView managed bean that simply calls another method to execute the search and then refreshes the navigator.

     public void searchOnEnter(ClientEvent clientEvent)
     {
       doRealSearchForFileItem();
       
       // refresh search navigator
       this.refresh();
     }
   

   Note:

   The Java-to-JavaScript transformation can lose type information for Numbers, chars, Java Objects, arrays, and nonstring CharSequences. Therefore, if an object being sent to the server was initially on the server, you may want to add logic to ensure the correct conversion. See What You May Need to Know About Marshalling and Unmarshalling Data.

3. To register the clientListener, in the Components window, from the Operations panel, drag a Client Listener and drop it as a child to the component that raises the event.

   Note:

   On the component that will fire the custom client event, the clientComponent attribute must be set to true to ensure that a client-side generated component is available.

4. In the Insert Client Listener dialog, enter the method and type for the JavaScript function. Be sure to include a library name if the script is not included on the page. The type can be any string used to identify the custom event, for example, enterPressedOnSearch was used in the File Explorer.
5. To register the server listener, in the Components window, from the Operations panel, drag a Server Listener and drop it as a sibling to the clientListener tag.
6. In the Insert Server Listener dialog, enter the string used as the Type value for the client listener, as the value for this server listener, for example enterPressedOnSearch.

   In the Properties window, for the method attribute, enter an expression that resolves to the method created in Step 2.

At runtime, when the user initiates the event, for example, pressing the Enter key, the client listener script executes. This script calls the AdfCustomEvent.queue() method, and a custom event of the specified event type is queued on the input component. The server listener registered on the input component receives the custom event, and the associated bean method executes.

Marshalling and unmarshalling is the process of converting data objects of a programming language into a byte stream and back into data objects that are native to the same or a different programming language. In ADF Faces, marshalling and unmarshalling refer to transformation of data into a suitable format so that it can be optimally exchanged between JavaScript on the client end and Java on the server end.

Note that there could be some loss of information during the conversion process. For example, say you are using the following custom event to send the number 1 and the String test, as shown in the following example:

AdfCustomEvent.queue(event.getSource(), "something", {first:1, second:"test"});

In the server-side listener, the type of the first parameter would become a java.lang.Double because numbers are converted to Doubles when going from JavaScript to Java. However, it might be that the parameter started on the server side as an int, and was converted to a number when conversion from Java to JavaScript took place. Now on its return trip to the server, it will be converted to a Double.

Mapping Java to JavaScript provides mapping between Java and JavaScript types.

Use the scrollComponentIntoViewBehavior tag when you want the user to be able to jump to a particular component on a page. This action is similar to an anchor in HTML. For example, you may want to allow users to jump to a particular part of a page using a commandLink component. For the richTextEditor and inlineFrame components, you can jump to a subcomponent. For example, Figure 6-1 shows a richTextEditor component with a number of sections in its text. The command links below the editor allow the user to jump to specific parts of the text.

Figure 6-1 scrollComponentIntoViewBehavior Tag in an Editor

You can also configure the tag to have focus switched to the component to which the user has scrolled.

Before you begin:

It may be helpful to have an understanding of behavior tags. See Using ADF Faces Client Behavior Tags.

To use the scrollComponentIntoViewBehavior tag:

1. Create a command component that the user will click to jump to the named component. For procedures, see How to Use Buttons and Links for Navigation and Deliver ActionEvents.
2. In the Components window, from the Operations panel, drag and drop a Scroll Component Into View Behavior as a child to the command component.
3. In the Insert Scroll Component Into View Behavior dialog, use the dropdown arrow to select Edit and then navigate to select the component to which the user should jump.
4. In the Properties window, set the focus attribute to true if you want the component to have focus after the jump.
5. For a richTextEditor or inlineFrame component, optionally enter a value for the subTargetId attribute. This ID is defined in the value of the richTextEditor or inlineFrame component.

   For example, the value of the subTargetId attribute for the scrollComponentIntoViewBehavior tag shown in Figure 6-1 is Introduction. The value of the richTextEditor is bound to the property shown in the following example. Note that Introduction is the ID for the first header.

   private static final String _RICH_SECTIONED_VALUE = 
     "<div>\n" + 
     "    <h2>\n" + 
     "      <a id=\"Introduction\"></a>Introduction</h2>\n" + 
     "    <p>\n" + 
     "      The ADF Table component is used to display a list of structured data. For example,\n" + 
     "      if we have a data structure called Person that has two properties - firstname and\n" + 
     "      lastname, we could use a Table with two columns - one for firstname, and the other\n" + 
     "      for lastname - to display a list of Person objects.\n" + 
     "    </p>\n" + 
     "  </div>\n" + 
     "  <div>\n" + 
     "    <h2>\n" + 
     "      <a id=\"The_Table_Model\"></a>The Table Model</h2>\n" + 
     "    <p>\n" + 
     . . .
      </div>";

1. In a managed bean, create a handler for the poll event. For information about managed beans, see Creating and Using Managed Beans.
2. In the Components window, from the Operations panel, drag and drop a Poll onto the page.
3. In the Properties window, expand the Common section and set the following:

   • Interval: Enter the amount of time in milliseconds between poll events. Set to 0 to disable polling.

   • PollListener: Enter an EL expression that evaluates to the method in Step 1.

   • Timeout: If you want to override the global timeout value in the web.xml file, set Timeout to the amount of time in milliseconds after which the page will stop polling and the session will time out.