How to Use Client-Side Events

5-10 Web User Interface Developers Guide for Oracle Application Development Framework

4. Add any attributes required by the function by dragging a Client Attribute

from the Operations panel of the Component Palette, and dropping it as a child to the selected component. Enter the name and value for the attribute in the Property Inspector. Example 5–5 shows the code used to set attribute values for the showAboutFileExplorerPopup function. Example 5–5 Adding Attributes af:commandMenuItem id=aboutMenuItem text={explorerBundle[menuitem.about]} clientComponent=true af:clientListener method=Explorer.showAboutFileExplorerPopup type=action af:clientAttribute name=popupCompId value=:fe:aboutPopup af:clientAttribute name=align value=end_after af:clientAttribute name=alignId value=aboutMenuItem af:commandMenuItem

5.3.2 How to Return the Original Source of the Event

The JavaScript method getSource returns the original source of a client event. For example, the File Explorer application contains the showAboutFileExplorerPopup function shown in Example 5–6 , that could be used by multiple events to set the alignment on a given popup dialog or window, using client attributes to pass in the values. Because each event that uses the function may have different values for the attributes, the function must know which source fired the event so that it can access the corresponding attribute values for more about using client attributes, see Section 5.3.3, How to Use Client-Side Attributes for an Event . Example 5–6 Finding the Source Component of a Client Event Explorer.showAboutFileExplorerPopup = functionevent { var source = event.getSource; var alignType = source.getPropertyalign; var alignCompId = source.getPropertyalignId; var popupCompId = source.getPropertypopupCompId; source.show{align:alignType, alignId:alignCompId}; event.cancel; } The getSource method is called to determine the client component that fired the current focus event, which in this case is the popup component. Note: If you use the attribute tag instead of the clientAttribute tag to add application-specific attributes or bonus attributes to a server component, those attributes are not included on the client component equivalent. You can use the clientAttribute tag on the JSF page, and the value will then be available on both the server and client. For information about posting client values back to the server, see Section 5.4, Sending Custom Events from the Client to the Server. For information about bonus attributes, see Section 3.7, Using Bonus Attributes for Client-Side Components. Handling Events 5-11

5.3.3 How to Use Client-Side Attributes for an Event

There may be cases when you want the script logic to cause some sort of change on a component. To do this, you may need attribute values passed in by the event. For example, the File Explorer application contains the showAboutFileExplorerPopup function shown in Example 5–7 , that can be used to set the alignment on a given popup component, using client attributes to pass in the values. The attribute values are accessed by calling the getProperty method on the source component. Example 5–7 Attribute Values Are Accessed from JavaScript 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; } The values are set on the source component, as shown in Example 5–8 . Example 5–8 Setting Attributes on a Component af:commandMenuItem id=aboutMenuItem text={explorerBundle[menuitem.about]} clientComponent=true af:clientListener method=Explorer.showAboutFileExplorerPopup type=action af:clientAttribute name=popupCompId value=:aboutPopup af:clientAttribute name=align value=end_after af:clientAttribute name=alignId value=aboutMenuItem af:commandMenuItem Using attributes in this way allows you to reuse the script across different components, as long as they all trigger the same event.

5.3.4 How to Block UI Input During Event Execution

There may be times when you do not want the user to be able to interact with the UI while a long-running event is processing. For example, suppose your application uses a button to submit an order, and part of the processing includes creating a charge to the user’s account. If the user were to inadvertently press the button twice, the account would be charged twice. By blocking user interaction until server processing is complete, you ensure no erroneous client activity can take place. The ADF Faces JavaScript API includes the AdfBaseEvent.preventUserInput function. To prevent all user input while the event is processing, you can call the preventUserInput function, and a glass pane will cover the entire browser window, preventing further input until the event has completed a roundtrip to the server. You can use the preventUserInput function only with custom events, events raised in a custom client script, or events raised in a custom client component’s peer. 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.