40 Using Contextual Events

This chapter describes how to create, publish, and subscribe to contextual events to facilitate communications between ADF Faces regions in the Fusion web application. It describes how to declaratively create the events, as well as programmatically use managed beans and JavaScript.

This chapter includes the following sections:

40.1 About Creating Contextual Events

The contextual events framework provides the communications between regions within a page. The framework provides the page with the ability to map events that are produced and consumed by the various regions on the page. You can use JDeveloper to declaratively publish events using the page definition file. Similarly, you can declaratively subscribe to those events from the page definition file. You can pass parameters with the event and implement handlers to respond to an event. Other ways to create contextual events include using managed beans and using JavaScript. Note that contextual events do not require regions to be refreshed for the region to uptake parameters.

Contextual events are not the same as the business events that can be raised by ADF Business Components or the events raised by UI components. For a description of these types of events, see Developing Web User Interfaces with Oracle ADF Faces. Contextual events can be used, however, in association with UI events. In this case, an action listener that is invoked due to a UI event can, in turn, invoke a method action binding that then raises the event.

Often a page or a region within a page needs information from somewhere else on the page or from a different region. While you can pass parameters to obtain that information, doing so makes sense only when the parameters are well known and the inputs are EL-accessible to the page. Parameters are also useful when a task flow may need to be restarted if the parameter value changes.

However, suppose you have a task flow with multiple page fragments that contain various interesting values that could be used as input on one of the pages in the flow. If you were to use parameters to pass the value, the task flow would need to surface output parameters for the union of each of the interesting values on each and every fragment. Instead, for each fragment that contains the needed information, you can define a contextual event that will be raised when the page is submitted. The page or fragment that requires the information can then subscribe to the various events and receive the information through the event.

In the Summit sample application for ADF task flows, contextual events are used in the Inventory Control tab of the main page to display the inventory for a selected product. When the Inventory Control tab is selected by the user, it displays two regions side by side. One region contains the showProducts.jsff page fragment which contains a table of the products available. The other region contains the showInventory.jsff page fragment which contains a DVT chart showing the product inventory percentages for different warehouses. Figure 40-1 shows the Inventory Control tab displaying the products and inventory regions.

Figure 40-1 Inventory Control Tab

Inventory Control tab of the Summit application.

The products region contains the show-products-task-flow task flow which utilizes the showProducts.jsff page fragment. The inventory region contains the product-inventory-task-flow task flow which utilizes the showInventory.jsff page fragment.

The main page index.jsff is the parent page for both regions, which are located in a child of the af:panelTabbed layout component.

A contextual event is passed from the products region to the inventory region so that the showInventory-task-flow can display the DVT chart for the selected product. When you create a event for the producer component using the Properties window, a event is registered in the producer's page definition file. In the Summit ADF sample application, the productSelected event is registered in the showProductsPageDef.xml file, as shown in Example 40-1

Example 40-1 Contextual Event in the Producer Page Definition File

<tree IterBinding="ProductVO1Iterator" id="ProductVO1">
      <nodeDefinition DefName="oracle.summit.model.views.ProductVO"
         Name="ProductVO10">
        <AttrNames>
          <Item Value="Id"/>
          <Item Value="Name"/>
          <Item Value="ShortDesc"/>
          <Item Value="LongtextId"/>
          <Item Value="ImageId"/>
          <Item Value="SuggestedWhlslPrice"/>
          <Item Value="WhlslUnits"/>
        </AttrNames>
        <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
          <event name="productSelected" eventType="Currency Change Event"
             customPayLoad="#{bindings.Id.inputValue}"/>
        </events>
      </nodeDefinition>
</tree>

When you use the overview editor for the page definition file to subscribe to events, an eventMap will be created to map events between producers and consumers.

In the Summit ADF sample application, the eventMap is create in the consumer's page definition file, as shown in Example 40-2.

Example 40-2 Event Map in the showInventoryPageDef.xml File

<eventMap xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
    <event name="productSelected">
      <producer region="*">
        <consumer handler="populateInventoryForProduct" region="">
        <parameters>
        <parameter name="productId" value="${payLoad}"/>
        </parameters>
        </consumer>
      </producer>
    </event>
</eventMap>

At runtime, when users enter the show-products-task-flow-definition and the showProducts.jsff page fragment, they are presented with a table of the products that are available. When the user selects a product from the list, a currency change event is invoked, resulting in the broadcast of the productSelected contextual event. In this example, a payLoad parameter containing the productId of the selected product is passed with the event.

This event is then consumed by the product-inventory task flow and its handler, the populateInventoryForProduct() method. This method uses the payLoad parameter to determine which product's inventory information to be displayed in the DVT component.

You will need to create the code for the event handler. For the Summit ADF sample application, the populateInventoryForProduct() handler was added to the InventoryVOImpl.java file because the InventoryVO view object contains the inventory data, as shown in Example 40-3.

Example 40-3 populateInventoryForProduct Event Handler for the Summit ADF Sample Application

public void populateInventoryForProduct( String productId ) {
          applyViewCriteria(getViewCriteria("InventoryVOCriteria"));
          setinputProductId( productId );
          executeQuery();
}
 
/**
 * Returns the variable value for Variable.
 * @return variable value for Variable
 */
public String getinputProductId() {
        return (String)ensureVariableManager().getVariableValue("inputProductId");
}
 
/**
 * Sets <code>value</code> for variable Variable.
 * @param value value to bind as Variable
 */
public void setinputProductId(String value) {
        ensureVariableManager().setVariableValue("inputProductId", value);
}

Events are configured in the page definition file for the page or region that will raise the event (the producer). In order to associate the producer with the consumer that will do something based on the event, you create an event map in the page definition file of the consuming page or the parent page. (The parent page is the page that contains both regions). If the consuming page is in a dynamic region, the event map should be in the page definition file of the consuming page and the producer's attribute region set to "*". The attribute region is set to "*" because at design time, the framework cannot determine the relative path to the producer.

You can raise a contextual event for an action binding, a method action binding, a value attribute binding, or a range binding (table, tree, or list binding). You also can conditionally fire an event and conditionally handle an event using EL expressions.

For action and method action bindings, the event is raised when the action or method is executed. The payLoad contains the method return value. You can also raise a contextual event from an ADF Faces event such as clicking a button or selecting from a menu. An eventBinding is created in the page definition to define the event.

For a value attribute binding, the event is triggered by the binding container and raised after the attribute is set successfully. The payLoad is an instance of DCBindingContainerValueChangeEvent, which provides access to the new and old value, the producer iterator, the binding container, and the source. If the payLoad property is changed to point to a custom data object, then the payLoad reference will return the object instead. Example 40-4 shows a value change event inside an attribute value binding associated with an input component. The event, valueChangeEvent, will be dispatched when the user changes the value of LAST_NAME in the page.

Example 40-4 Value Attribute Event in the Page Definition File

<attributeValues IterBinding="DeptView1Iterator" id="Dname"
            xmlns="http://xmlns.oracle.com/adfm/jcuimodel">
    <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
            <event name="valueChangeEvent"/>
    </events>                     
    <AttrNames xmlns="http://xmlns.oracle.com/adfm/uimodel">
            <Item Value="LAST_NAME"/>
    </AttrNames>
</attributeValues>
</bindings>
<eventMap xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
    <event name="valueChangeEvent">
        <producer region="LAST_NAME">
            <consumer region="" handler="consumeEvent"/>
        </producer>
    </event>
</eventMap>

For an range binding (tree, table, list), the event is raised after the currency change has succeeded. The payLoad is an instance of DCBindingContainerValueChangeEvent, which provides access to the new and old value, the producer iterator, the binding container, and the source. Example 40-2 shows the event map for a currency change event associated with a range binding.

Value attribute binding and range binding contextual events may also be triggered by navigational changes. For example, if you create an event inside a tree table binding, the event will be dispatched when the user selects a different node of the tree in the page.

You use the Contextual Events section under the Behavior section in the Properties window to create and publish contextual events. The Contextual Events panel will only appear when you select eligible components or regions in the page, as shown in Figure 40-2.

Figure 40-2 Contextual Events Panel in the Properties Window

Property Inspector for Contextual Events

You subscribe to contextual events using the overview editor for page definition file's Contextual Events tab Subscriber section, as shown Figure 40-3

Figure 40-3 Page Definition Contextual Events Tab

Page Definition Contextual Events Tab

40.1.1 Contextual Events Use Cases and Examples

There are three kinds of communication patterns between a region and the parent page: parent to region, region to parent, and region to region. The contextual events framework is the most powerful communication implementation that works for all three of these scenarios. Also note that contextual events do not require a region to be refreshed in order to consume input parameters.

You should use contextual events to communicate between ADF regions. While it is possible to use ADF task flow parameters to communicate between regions, doing so may create direct dependencies between the regions. ADF task flow parameters may be fine for static regions, but using contextual events will allow you to implement independent communications between regions.

For example, a page may contain a region with a form for entering employee information. When the user updates the employee Id and presses the submit button, a value change contextual event is raised and the employee Id value is also passed as payLoad. On the same page, another region subscribes to and consumes the event and displays departmental information about the selected employee based on the payLoad information passed with the contextual event.

40.1.2 Additional Functionality for Contextual Events

You may find it helpful to understand other ADF features before you work with contextual events. Following are links to other functionality that may be of interest.

40.2 Creating Contextual Events Declaratively

You create contextual events by first creating and publishing the event on the producer based on a method action, action, value attribute, or list binding. On the consumer, you subscribe to the event and create a handler to process the event.

Typically, you create a parent page with regions that contain task flows and view activities. You create contextual events in one region to be published for consumer event handlers in the other region. For more information about using task flows and regions, see Chapter 23, "Using Task Flows as Regions."

Note:

You can also publish an action contextual event from code (for example, from within a managed bean). You can use getBindingContainer().getEventDispatcher which returns an instance of EventDispatcher. EventDispatcher has public APIs which you can use to programmatically raise contextual events.

40.2.1 How to Publish Contextual Events

You use the Properties window to create contextual events in the page where the contextual event will be produced. That is, the producer's page is the page where the contextual event is generated. For instance, clicking a button on a page that would trigger a contextual event to be consumed by another component. The page that contains the button is the producer's page.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.2, "Creating Contextual Events Declaratively."

You may also find it helpful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

You will need to complete this task:

Decide on the type of component you want to use to raise the contextual event. If you plan to use a method action binding, you must have already created the method to be dropped onto the page.

To create a contextual event:

  1. In the page where you want to publish the contextual event, drag and drop a component from the Data Controls panel to the page.

    This is the component that will trigger the event. It must have a method action, action, value attribute, or list binding event.

  2. In the Properties window, expand the Behavior section.

  3. In the Publish Events section, click the Add icon.

  4. In the Publish Contextual Events dialog:

    1. Select Create New Event.

    2. Enter the name of the event.

    3. If your component is a table, tree, or tree table, a Node field appears for you to enter the node that will publish the event upon a change event.

    4. Select Pass Custom Value From if you want to pass payload data to the consumer.

    5. If you are passing payload data, select the type of data from the dropdown list. Normally, the parameter is {$payLoad}

      For instance, if you want to pass an attribute value from the producer page to the consumer page, you can select Page Data and select the attribute from the tree structure.

    6. You can conditionally raise the event by entering an EL expression in the Raise Condition tab.

      For instance, entering an expression such as ${bindings.LAST_NAME.inputValue == 'KING'} will cause the event to be raised only if the customer's last name is KING.

    7. Click OK.

      The event is created on the page, but it is not ready for publishing until it is associated with the component binding.

      Figure 40-4 Publish a Contextual Event

      Publish a Contextual Event

40.2.2 How to Subscribe to and Consume Contextual Events

You use the overview editor for page definition files to subscribe to contextual events. The overview editor displays the current region and its child regions. Only the regions that are shown can subscribe to contextual events.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.2, "Creating Contextual Events Declaratively."

You may also find it helpful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

You will need to complete this task:

Create a contextual event in the page definition file, as described in Section 40.2.1, "How to Publish Contextual Events."

To subscribe and consume the event:

  1. Create a handler to process the event and its payload data.

    In the Summit ADF sample application, the PopulateInventoryForProduct handler method was created in the InventoryVO view object by adding the code to the InventoryVOImpl.java file.

    The method appears in the BackOfficeAppModuleDataControl application module.

  2. In the consuming page, add the components that will respond to the event.

    In the Summit ADF sample application, a DVT component is added to the page to display the inventory available in different warehouses.

    The DVT component will receive the data from the PopulateInventoryForProduct method.

  3. In the Applications window, double-click the page definition file that will contain the event map.

    In the Summit ADF sample application, the showInventoryPageDef.xml page definition file will have the event map.

  4. In the overview editor, click the Bindings and Executables tab and then click the Add icon for the Bindings section

  5. In the Insert Item dialog, select methodAction and click OK.

  6. In the Create Action Binding dialog:

    1. Expand the data collection where you have created your handler.

    2. Select the handler.

    3. Click OK.

  7. In the overview editor Contextual Events tab, click Subscribers and click the Add icon in the Event Subscribers section.

  8. In the Subscribe to Contextual Event dialog:

    1. Enter the event name or click the Search icon to start the Select Contextual Event dialog.

      If you have started the Select Contextual Events dialog, select the event from the tree and click OK.

    2. Select the producer or <Any> from the Publisher dropdown list. A contextual event can have more than one producer.

      Selecting <Any> will allow the consumer to subscribe to any producer producing the selected event. In the page definition file, the producer attribute will be set to the wildcard "*". If your producer is in a dynamic region, you should set this field to <Any> so that the subscriber can consume from any producer.

    3. Click the Search icon next to the Handler field.

    4. In the Select Handler dialog, select the event handler from the tree and click OK.

    5. If the handler requires parameters, click the Parameters tab, click Add, and enter name-value pair as parameters.

    6. If you want to conditionally handle the event, select the Handle tab, and enter an EL Expression that determines the conditions under which the handler will process the event.

    7. Click OK.

    Figure 40-5 Subscribe to a Contextual Event

    Subscribe to a Contextual Event

    Note:

    You can edit the event map by right-clicking the page definition in the Structure window and choosing Edit Event Map. You can also edit event attributes in the page definition file or in the Properties window.

40.2.3 What Happens When You Create Contextual Events

When you create an event for the producer, JDeveloper adds an events element to the page definition file. Each event name is added as a child. Example 40-5 shows the productSelected event defined in the producer page definition file as a currency change event.

Example 40-5 Event Definition for the Producer

<tree IterBinding="ProductVO1Iterator" id="ProductVO1">
      <nodeDefinition DefName="oracle.summit.model.views.ProductVO"
        Name="ProductVO10">
        <AttrNames>
          <Item Value="Id"/>
          <Item Value="Name"/>
          <Item Value="ShortDesc"/>
          <Item Value="LongtextId"/>
          <Item Value="ImageId"/>
          <Item Value="SuggestedWhlslPrice"/>
          <Item Value="WhlslUnits"/>
        </AttrNames>
        <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
          <event name="productSelected" eventType="Currency Change Event"
           customPayLoad="#{bindings.Id.inputValue}"/>
          </events>
      </nodeDefinition>
</tree>

In the consumer page definition file, a method action binding is created to respond to the event. Example 40-6 shows the method action binding defined in the showInventoryPageDef page definition file.

Example 40-6 Method Action Definition in the Page Definition File

<methodAction id="populateInventoryForProduct" RequiresUpdateModel="true"
          Action="invokeMethod"
          MethodName="populateInventoryForProduct"
          IsViewObjectMethod="true"
                  DataControl="BackOfficeAppModuleDataControl"
                  InstanceName="data.BackOfficeAppModuleDataControl.InventoryVO1">
      <NamedData NDName="productId" NDType="java.lang.String"/>
</methodAction>

When the currency change occurs, the event is broadcasted to its consumers. The method action definition is defined in the consuming page definition file.

When you configure an event map, JDeveloper creates an event map entry in the corresponding page definition file. Example 40-7 shows the event map on the showInventoryPageDef page definition file that maps the productSelected event from the showproductstaskflowdefinition1 region to the productinventorytaskflowdefinition1 region. It also maps the populateInventoryForProduct handler method bindings that is defined in the showInventoryPageDef page definition file. The handler processes the payLoad information (containing the productID) and passes it to the DVT component so it can query the warehouse inventory for that product.

Example 40-7 Event Map in the Consuming Page Definition File

<eventMap xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
    <event name="productSelected">
      <producer region="*">
        <consumer handler="populateInventoryForProduct" region="">
        <parameters>
        <parameter name="productId" value="${payLoad}"/>
        </parameters>
        </consumer>
      </producer>
    </event>
</eventMap>

40.2.4 How to Control Contextual Events Dispatch

You can control the dispatch of contextual events to child regions at the application level or at the page level.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.2, "Creating Contextual Events Declaratively."

You may also find it helpful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

To disable event dispatch:

  1. To disable event dispatch at the application level, set the dynamicEventSubscriptions property to false in the adf-config.xml file, as shown in Example 40-8.

    You can disable the event dispatch to regions that have an event map with producers as wildcards.

    Example 40-8 Disabling Contextual Event Dispatch at the Application Level Using adf-config.xml

    <?xml version="1.0" encoding="windows-1252" ?>
    <adf-config xmlns="http://xmlns.oracle.com/adf/config"
         xmlns:cef="http://xmlns.oracle.com/adfm/contextualEvent">
         <cef:DynamicRegionEventsConfig dynamicEventSubscriptions="false">
         </cef:DynamicRegionEventsConfig>
    </adf-config>
    
  2. To disable event dispatch at the individual page level, set the dynamicEventSubscriptions property to false in the associated page definition file, as shown in Example 40-9.

    Contextual events will not be passed to the page and any of its children.

    Example 40-9 Disabling Contextual Event Dispatch for a Page Using the Page Definition File

    <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                    version="11.1.1.52.8" id="viewBPageDef" Package="view.pageDefs"
                    DynamicEventSubscriptions="false">
    

40.2.5 What Happens at Runtime: Contextual Events

If both the event producer and the consumer are defined in the same page definition file, then after the corresponding page is invoked and the binding container is created, the event is raised when:

  • The corresponding method or action binding is executed

  • A value binding is set successfully

  • A range binding currency is set successfully

For a method binding, the result of the method execution forms the payload of the event, and the event is queued. In the Invoke Application phase of the JSF lifecycle, all the queued events will be dispatched. The event dispatcher associated with the binding container checks the event map (also in the binding container, as it is part of the same page definition file) for a consumer interested in that event and delivers the event to the consumer.

When the producer and consumer are in different regions, the event is first dispatched to any consumer in the same container, and then the event propagation is delegated to the parent binding container. This process continues until the parent or the topmost binding container is reached. After the topmost binding container is reached, the event is again dispatched to child-binding containers that have regions with pages that have producer set to wildcard "* ".

40.3 Creating Contextual Events Manually

You create contextual events by first creating the event on the producer. You then determine the consumer of the event, and map the producer to the consumer.

40.3.1 How to Create Contextual Events Manually

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.3, "Creating Contextual Events Manually."

You may also find it helpful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

You will need to complete this task:

Create a contextual event that has a method binding, action binding, value attribute binding, or list binding on the producer page.

To create a contextual event:

  1. In the Applications window, double-click the page definition file that contains the binding for the producer of the event.

    A producer must have an associated binding that will be used to raise the event. For example, if a method or operation will be the producer, the associated action binding or method action binding will contain the event.

  2. In the Structure window, right-click the binding for the producer and choose Insert inside binding name > events or Insert inside binding name > Contextual Events > events.

  3. In the Structure window, right-click the events element just created, and choose Insert inside events > event.

  4. In the Insert event dialog, enter a name for the event in the name field, and click Finish.

    The event is now created. By default, any return of the associated method or operation will be taken as the payload for the event and stored in the EL-accessible variable ${data.payLoad}. You now need to map the event to the consumer, and to configure any payload that needs to be passed to the consumer.

  5. In the Applications window, double-click the page definition file that contains the binding for the consumer.

    The binding container represented by this page provides access to the events from the current scope, including all contained binding containers (such as task flow regions). If regions or other nested containers need to be aware of the event, the event map should be in the page definition of the page in the consuming region.

  6. In the Structure window, right-click the topmost node that represents the page definition, and choose Edit Event Map.

    Note:

    If the producer event comes from a page in an embedded dynamic region, you may not be able to edit the event map using the Event Map Editor. You can manually create the event map by editing the page definition file or use insert inside steps, as described in Section 40.3, "Creating Contextual Events Manually."

  7. In the Event Map Editor, click the Add icon to add an event entry.

  8. In the Add New EventMap Entry dialog, do the following:

    1. Use the Producer dropdown menu to choose the producer.

    2. Use the Event Name dropdown menu to choose the event.

    3. Use the Consumer dropdown menu to choose the consumer. This should be the actual method that will consume the event.

    4. If the consuming method or operation requires parameters, click the Add icon.

      In the Param Name field, enter the name of the parameter expected by the method. In the Param Value field, enter the value. If this is to be the payload from the event, you can access this value using the ${data.payLoad} expression. If the payload contains many parameters and you don't need them all, use the ellipses button to open the Expression Builder dialog. You can use this dialog to select specific parameters under the payload node.

      You can also click the Parameters ellipses button to launch the selection dialog.

    5. Click OK.

  9. In the Event Map Editor, click OK.

40.4 Creating Contextual Events Using Managed Beans

You can publish an action contextual event from code such as from within a managed bean.

40.4.1 How to Create Contextual Events Using Managed Beans

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.4, "Creating Contextual Events Using Managed Beans."

You may also find it helpful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

To create contextual events using managed beans:

  1. Create a method in a managed bean to generate the contextual event.

    Example 40-10 shows managed bean code that perform an action when a button is pressed. The myActionPerformed method is invoked and calls methods to generate the contextual event with "myString" as the payLoad:

    Example 40-10 Managed Bean to Process Contextual Event

    BindingContainer bc BindingContext.getCurrent().getCurrentBindingsEntry();
    JUCtrlActionBinding actionBnd =
      (JUCtrlActionBinding)bc.getControlBinding("eventProducer");
    ...
    ((DCBindingContainer)bc).getEventDispatcher().queueEvent(actionBnd.
       getEventProducer(),"myString");
    
  2. Bind the producer component to the method in the managed bean.

    Example 40-11 shows code for a producer associated with a command button that invokes an action binding and the consumer is an outputText component that displays a string. They are both on the same page.

    Example 40-11 Event Producer and Event Consumer on the JSF

    <af:form id="f1">
         <af:button value="eventProducerButton1" id="cb1"
                    action="#{MyBean.myActionPerformed}"/>
         <af:panelLabelAndMessage label="#{bindings.return.hints.label}"id="plam1">
              <af:outputText value="#{bindings.return.inputValue}" id="ot1"/>
         </af:panelLabelAndMessage>
    </af:form>
    

40.4.2 What Happens When You Create Contextual Events Using Managed Beans

The page definition file contains the method action bindings for the producer, the consumer, and the event map, as shown in Example 40-12.

Example 40-12 Page Definition with Event Producer, Event Consumer, and Event Map

<executables>
    <variableIterator id="variables">
      <variable Type="java.lang.String" Name="eventConsumer_return"
                IsQueriable="false" IsUpdateable="0"
                DefaultValue="${bindings.eventConsumer.result}"/>
    </variableIterator>
</executables>
<bindings>
     <methodAction id="eventProducer"
                  InstanceName="AppModuleDataControl.dataProvider"
                  DataControl="AppModuleDataControl" RequiresUpdateModel="true"
                  Action="invokeMethod" MethodName="eventProducer"
                  IsViewObjectMethod="false"
                  ReturnName="AppModuleDataControl.methodResults.eventProducer_
                       AppModuleDataControl_dataProvider_eventProducer_result">
            <events xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
                  <event name="myEvent"/>
            </events>
     </methodAction>
     <methodAction id="eventConsumer" RequiresUpdateModel="true"
                  Action="invokeMethod" MethodName="eventConsumer"
                  IsViewObjectMethod="false" DataControl="AppModuleDataControl"
                  InstanceName="AppModuleDataControl.dataProvider"
                  ReturnName="AppModuleDataControl.methodResults.eventConsumer_
                        AppModuleDataControl_dataProvider_eventConsumer_result">
               <NamedData NDName="str" NDValue="test" NDType="java.lang.String"/>
    </methodAction>
    <attributeValues IterBinding="variables" id="return">
        <AttrNames>
             <Item Value="eventConsumer_return"/>
        </AttrNames>
    </attributeValues>
</bindings>
<eventMap xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
    <event name="myEvent">
      <producer region="eventProducer">
        <consumer region="" handler="eventConsumer">
          <parameters>
            <parameter name="test" value="${data.payLoad}"/>
          </parameters>        
        </consumer>
      </producer>
    </event>
</eventMap>

40.5 Creating Contextual Events Using JavaScript

Every action and method binding that is accessible from a managed bean can be invoked from JavaScript. ADF Faces provides an af:serverListener operation component that can be used to call a managed bean method from client-side JavaScript. To invoke this component using the referenced managed bean method, use the BindingContext object to look up the current BindingContainer and to access the OperationBinding or a JUEventBinding binding. The af:serverListener component can also be used to send a message payload from the browser client to the managed bean method.

40.6 Creating the Event Map Manually

Under most circumstances, you can create the event map using the Event Map Editor as described in Section 40.3, "Creating Contextual Events Manually." However, in situations such as when the producer event is from a page in an embedded dynamic region, the Event Map Editor at design time cannot obtain the necessary information to create an event map.

40.6.1 How to Create the Event Map Manually

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.6, "Creating the Event Map Manually."

You may also find it useful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

To create the event map manually:

  1. In the Applications window, double-click the page definition file that contains the binding for the consumer.

  2. In the Structure window, right-click the topmost node that represents the page definition, and choose Insert inside pagedef name > eventMap.

  3. In the Structure window, select the eventMap node, right-click and choose Insert inside eventMap > event.

  4. In the Insert Event dialog, enter the name of the event and click OK.

    Repeat steps 3 and 4 to add more events.

  5. Select the event node, right-click and choose Insert inside event > producer.

  6. In the Insert Producer dialog, enter the name of the binding that is producing this event and click OK.

    You can also enter the name of the region which has the event producer, in which case all the consumers specified under this tag can consume the event. You can also enter "*" to denote that this event is available for all consumers under this tag.

  7. Select the producer node, right-click, and choose Insert inside producer > consumer.

  8. In the Insert Consumer dialog, enter the name of the handler that will consume the event and click OK.

    Repeat steps 7 and 8 to add more consumers.

  9. If there are parameters being passed, add the parameter name and value.

    1. Select the consumer node, right-click, and choose Insert inside consumer > parameters.

    2. Select the parameters node, right-click, and choose Insert inside parameters > parameter.

    3. In the Insert Parameter dialog, enter the name of the parameter and the value of the parameter and click OK. The value can be an EL expression.

      Repeat this step to add more parameters.

40.7 Registering a Custom Dispatcher

By default, the contextual event framework uses EventDispatcherImpl to dispatch events that would traverse through the regions. You can create a custom event dispatcher to override the default event dispatcher to provide custom behaviors. After you have created the custom event dispatcher, you must register it in the Databindings.cpx file to override the default dispatcher.

40.7.1 How to Register a Custom Dispatcher

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you create contextual events. For more information, see Section 40.7, "Registering a Custom Dispatcher."

You may also find it useful to understand functionality that can be used with contextual events. For more information, see Section 40.1.2, "Additional Functionality for Contextual Events."

To register a custom event dispatcher:

  1. Create a custom event dispatcher Java class based on the EventDispatcher class.

  2. Register the custom event dispatcher in the Databindings.cpx file with a fully qualified name using the following format:

    EventDispatcher="package_name.CustomEventDispatcher_name"
    

    Example 40-13 shows the code for a custom event dispatcher called NewCustomEventDispatcher created in package NewPackage.

    Example 40-13 Adding Custom Event Dispatcher in the Databindings.cpx File

    <Application xmlns="http://xmlns.oracle.com/adfm/application"
                 version="11.1.1.51.60" id="DataBindings" SeparateXMLFiles="false"
                 Package="project3" ClientType="Generic"
                 EventDispatcher="NewPackage.NewCustomEventDispatcher">
    
  3. Create the event in the producer's page definition. For more information, see Section 40.2, "Creating Contextual Events Declaratively," or Section 40.3, "Creating Contextual Events Manually."

  4. Create the event map in the consumer region if the consumer is in a dynamic region. If the consumer is not in a dynamic region, you can also specify the event map in the parent page which holds both the producer and consumer regions. For more information, see Section 40.6, "Creating the Event Map Manually."