How to Return the Original Source of the Event

5-12 Web User Interface Developers Guide for Oracle Application Development Framework Additionally, the event must propagate to the server. Example 5–9 shows how you can use preventUserInput in your JavaScript. Example 5–9 Blocking UI Input function queueEventevent { event.cancel; cancel action event var source = event.getSource; var params = {}; var type = customListener; var immediate = true; var isPartial = true; var customEvent = new AdfCustomEventsource, type, params, immediate; customEvent.preventUserInput; customEvent.queueisPartial; }

5.3.5 How to Prevent Events from Propagating to the Server

By default, some client events propagate to the server once processing has completed on the client. In some circumstances, it is desirable to block this propagation. For instance, if you are using a commandButton component to execute JavaScript code when the button is clicked, and there is no actionListener event listener on the server, propagation of the event is a waste of resources. To block propagation to the server, you call the cancel function on the event in your listener. Once the cancel function has been called, the isCanceled function will return true. Example 5–10 shows the showAboutFileExplorerPopup function, which cancels its propagation. Example 5–10 Canceling a Client Event from Propagating to the Server Explorer.showAboutFileExplorerPopup = functionevent { var source = event.getSource; var alignType = source.getPropertyalign; var alignCompId = source.getPropertyalignId; var popupCompId = source.getPropertypopupCompId; var aboutPopup = event.getSource.findComponentpopupCompId; aboutPopup.show{align:alignType, alignId:alignCompId}; event.cancel; } Canceling an event may also block some default processing. For example, canceling an AdfUIInputEvent event for a context menu will block the browser from showing a context menu in response to that event. The cancel function call will be ignored if the event cannot be canceled, which an event indicates by returning false from the isCancelable function events that cannot be canceled show no in the Is Cancelable column in Table 5–3 . This generally means that the event is a notification that an outcome has already completed, and cannot be blocked. There is also no way to uncancel an event once it has been canceled. Handling Events 5-13

5.3.6 What Happens at Runtime: How Client-Side Events Work

Event processing in general is taken from the browsers 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 rich client JavaScript event object that wraps that DOM event, returning it to the page, which queues the event for more information about peers and the ADF Faces architecture, see Chapter 3, Using ADF Faces Architecture . The event queue on the page most commonly empties at the end of the browsers 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 peers 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 peers DispatchComponentEvent function. Note that client event listeners do not receive the event, only the peers do. Event bubbling can be blocked by calling an events stopBubbling function, after which the isBubblingStopped function will return true, and bubbling will not continue. As with cancelling, you cannot undo this call.

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.

5.3.7 What You May Need to Know About Using Naming Containers

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 Example 5–11 . 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.