How to Block UI Input During Event Execution

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. 5-14 Web User Interface Developers Guide for Oracle Application Development Framework The getSource method accesses the AdfUIComponent class, which can then be used to find the component. Example 5–11 JavaScript Using the findComponent Method function showPopupevent { event.cancel; var source = event.getSource; var popup = source.findComponentpopup; 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 more information about working with naming containers, see Section 3.5, Locating a Client Component on a Page.

5.4 Sending Custom Events from the Client to the Server

While the clientAttribute tag supports sending bonus attributes from the server to the client, those attributes are not synchronized back to the server. To send any custom data back to the server, use a custom event sent through the AdfCustomEvent class and the serverListener tag. The AdfCustomEvent.queue JavaScript method enables you to fire a custom event from any component whose clientComponent attribute is set to true. The custom event object contains information about the client event source and a map of parameters to include on the event. The custom event can be set for immediate delivery that is, during the Apply Request Values phase, or non-immediate delivery that is, during the Invoke Application phase. For example, in the File Explorer application, after entering a file name in the search field on the left, users can press the Enter key to invoke the search. As Example 5–12 shows, this happens because the inputText field contains a clientListener that invokes a JavaScript function when the Enter key is pressed. Example 5–12 clientListener Invokes JavaScript Function and Causes ServerLIstener to Be Invoked Code on the JSF page... af:inputText id=searchCriteriaName value={explorer.navigatorManager.searchNavigator. searchCriteriaName} shortDesc={explorerBundle[navigator.filenamesearch]} af:serverListener type=enterPressedOnSearch method={explorer.navigatorManager. searchNavigator.searchOnEnter} af:clientListener type=keyPress method=Explorer.searchNameHandleKeyPress af:inputText Code in JavaScript file... Explorer.searchNameHandleKeyPress = function event { if event.getKeyCode==AdfKeyStroke.ENTER_KEY { var source = event.getSource; AdfCustomEvent.queuesource, enterPressedOnSearch,