Event Parameter and Parameter Mapping 

Overview

Action event handlers are independent from the UI element that was used to trigger an event. They are independent, because a UI element event is bound to the event handler of an action and this event handler uses an instance of the action class.

Parameters can be passed to certain UI element events. For example, the onSelect event of the DropDownByIndex UI element contains the parameter index.

These event parameters are not defined in the event source - that is, the UI element - but in the implementation of the event handler. Therefore, the implementations in the controller remain independent from the UI element.

If an action is bound to such a UI element, it is also specified which event parameters are to be used as the parameters for the action event handler. This process is known as parameter mapping. It is the mapping of event parameters in the event source, the UI element, to the signature of the event handler.

This is needed, for example, if you want to replace a table with a dropdown list box without modifying the source code of the event handler in the controller. The onLeadSelect event, which occurs when a table cell is selected, provides the parameters col and row. The onSelect event of a dropdown list box contains the parameter index. If you want to exchange the UI elements, you must define a parameter mapping (see example).

The parameter mapping represents an instance of the UI element event. Therefore, the parameter mapping is defined at UI element level. The wdDoModifiyView method is provided to describe the parameter mapping of a UI element event.

Example

The following source code example provides the UI element and the corresponding parameter mapping:

public static void wdDoModifyView(IPrivateMyView wdThis, IPrivateMyView.IContextNode wdContext, IWDView view, boolean firstTime)   {     //@@begin wdDoModifyView     if (firstTime)     {       // Access UI element with id “theTable”       IWDTable theTable = (IWDTable) view.getElement("theTable");         // Map parameter row to parameter newSelection. We do not care       // about the second parameter “col” also defined for UI event // OnLeadSelect       theTable.mappingOfOnLeadSelect(). addSourceMapping("row","theNewIndex");          }     //@@end   }

If you replace the table with a DropDownByIndex UI element, you can use the same action event handler without modifying it. However, you must redefine the parameter mapping, because the DropDownByIndex UI element triggers the event onSelect, and this event contains the parameter index.

public static void wdDoModifyView(IPrivateMyView wdThis, IPrivateMyView.IContextNode wdContext, IWDView view, boolean firstTime)   {     //@@begin wdDoModifyView     if (firstTime)     {       // Access UI element with id “theTable”       IWDDropDownByIndex theDropDown = (IWDDropDownByIndex) view.getElement("theDropDown");   // Map parameter index to parameter newSelection.       theDropDown.mappingOfOnSelect(). addSourceMapping("index","theNewIndex");             }     //@@end   }

Mapping Constants

You can also map constants using parameter mapping.

In a Web Dynpro application, you can create different buttons at runtime whose maximum number cannot be specified at design time. You can create the buttons and the actions at runtime. However, you can bind all dynamically created buttons to a single action event handler. This special function is based on constant mapping. Without having a reference to a runtime information of the UI element in an action event handler, a Web Dynpro application can determine which button the user selected. This is possible, because constant parameters are mapped to an action event handler.

The event handler can read these parameters and therefore determine which UI element triggered the event. You can replace a button with a link without having to change the source code in the event handler. See the following example source code:

 

public static void wdDoModifyView(IPrivateMyView wdThis, IPrivateMyView.IContextNode wdContext, IWDView view, boolean firstTime)   {     //@@begin wdDoModifyView     if (firstTime)     {       for (int index = 0;index < 10;index ++)       {   IWDButton theButton = (IWDButton) view.createElement(IWDButton.class,"theButton"+index);            theButton.setText(getSomeText(index));         theButton.setOnAction(wdThis.wdGetGenericAction());   theButton.mappingOfOnAction().addParameter("commandId",index);       }     }     //@@end   }     /** declared validating action event handler */   public void onGenericAction (IWDCustomEvent wdEvent , int commandId )   {     //@@begin onGenericAction(ServerEvent)    switch(commandId)    {       case 0:  ExecuteCommand_1();          break;       case 1:  ExecuteCommand_2();             break;             ...    }     //@@end   }

Common Event Parameter nodeElement

The parameter nodeElement of the type IWDNodeElement can be used for all events. This parameter must explicitly added for parameter mapping. Use the following code:

<UI element instance>.mappingOf<name of the event>().addSourceMapping ("nodeElement","nodeElement");

The parameter nodeElementreferences to the corresponding node element in the context to which the UI element is assigned. For example, when you use a button as a cell editor in a table, this parameter can be used to determine in which table row the button was pressed without having to analyze the lead selection.

Type Conversion of Complicated Event Parameter Data Types

The Web Dynpro Framework supports type conversion from the type of the event parameter to the type of the event handler parameter. Above all, this affects those event parameters that represent complicated data types, for example, the pathparameter of the onAction event of a TreeNodeType element. When triggering the onAction action, the event passes path the parameter on as data type String, which corresponds to the path to the context node that triggered the event. However, at runtime, a node element of type IWDNodeElementcorresponds to the tree node in the context. The Web Dynpro Framework can convert the event parameter data type (in this case: String) to the IWDNodeElement data type, if you declare a Java class or interface as the type of the event handler parameter that implements or extends the IWDNodeElement interface. You can find an example of this in the description of the onLoadChildren event for IWDTreeNodeType.

See also IWDParameterMapping.