Parameter Mapping 

Purpose

To ensure that server-side controllers can react intelligently to user actions on the client, it is necessary to associate parameters with certain client-side events. For instance, when the user selects an item from a dropdown list, the server-side controller needs to know more than just the fact that an item has been selected; it needs to know exactly which item has been selected. Therefore, when a dropdown list fires its onSelect event, you must ensure that the index of the selected item is also received.

Process Flow

Event parameter names are hard-coded within each UI element. If an event has an associated event parameter, then the UI element will automatically place a value into the event parameter. This part of the coding is done for you automatically; however, you must ensure that the value of the client-side event parameter is received by the server-side action handler.

In the case of the DropDownByIndex UI element, the hard-coded parameter is called index. Its value will be supplied automatically as part of the client-side event – but this is all happening on the client-side. You need to transport the value of index back to the server, and then ensure that the client-side event parameter becomes a parameter to the server-side action handler.

This process is known as parameter mapping, and is achieved as follows:

·       Obtain the name of the parameter associated with the client-side event. This can be found by looking in the documentation of the UI element and looking at the mappingOf{ui_event}() method. For example, by looking at IWDCheckBox.mappingOfOnToggle(), you will find that the event has a parameter called checked which is of type boolean.

·       Create an action {act} in the view controller.

·       Define a parameter for the action of the same data type as the event parameter. You will often find it helpful to make the server-side action parameter name the same as the client-side event parameter name, though this is not mandatory.

·       Associate the event parameter with the action parameter. The coding to do this is shown in the next example.

Example

Basic parameter mapping example

In this example, the checked parameter of the onToggle event of a checkbox UI element will be associated with a parameter called checkBoxState in the corresponding action handler.

1.      Create an action in a view controller to handle the change of state in a checkbox UI element.  The checkbox is called myCheckBox and will be associated with an action called HandleCheckBox.

2.      Define a parameter called checkBoxState of type boolean against the action handler method onActionHandleCheckBox.

3.      Place the following coding in the wdDoModifyView() method of the view controller. This coding only needs to be executed once during the view controller’s lifecycle, therefore we first check whether the firstTime flag is true.

if (firstTime) {

  // Get a reference to the checkbox UI element

  IWDCheckBox cb =

    (IWDCheckBox)view.getElement("myCheckBox");

  // Link the client-side event parameter ‘checked’ to

  // the server-side action parameter ‘checkBoxState’

  cb.mappingOfOnToggle().addSourceMapping("checked",

                                          "checkBoxState");

}

Now, whenever this particular checkbox is toggled, the client-side event parameter checked that belongs to the onToggle event, will be passed through to the server-side action handler HandleCheckBox as the boolean variable checkBoxState.

 

Action handler generalisation

Since the event-to-action parameter mapping is specific to the UI element and not the action, it is perfectly possible to generalise the use of an action handler so that it can respond to events from multiple UI elements. You can extend the first example so that the action handler HandleCheckBox can process any onToggle event from any checkbox on the current view.

In order to make an action handler work in this generic manner, you must define an extra parameter for HandleCheckBox that will identify which checkbox raised the event.

This extra parameter has nothing to do with the client-side event itself; therefore, it is completely independent from the client layer. The following code extends the above coding example.

·   Against action handler HandleCheckBox, define a new parameter called checkBoxName of type String.

·   You now have three checkboxes whose onToggle events will all be processed by HandleCheckBox.

·   For each checkbox UI element, you must now associate a fixed value to the checkBoxName parameter. The coding is as follows:

if (firstTime) {

  // Get references to all checkbox UI elements

  IWDCheckBox cb1 = (IWDCheckBox)view.getElement("checkBox1");

  IWDCheckBox cb2 = (IWDCheckBox)view.getElement("checkBox2");

  IWDCheckBox cb3 = (IWDCheckBox)view.getElement("checkBox3");

 

  // Link the client-side event parameter ‘checked’ to

  // the server-side action parameter ‘checkBoxState’

  cb1.mappingOfOnToggle().addSourceMapping("checked",

                                           "checkBoxState");

  cb2.mappingOfOnToggle().addSourceMapping("checked",

                                           "checkBoxState");

  cb3.mappingOfOnToggle().addSourceMapping("checked",

                                           "checkBoxState");

 

  // Hardcode the checkbox names for each action parameter

  cb1.mappingOfOnToggle().addParameter("checkBoxName",

                                       cb1.getId());

  cb2.mappingOfOnToggle().addParameter("checkBoxName"

                                       cb2.getId());

  cb3.mappingOfOnToggle().addParameter("checkBoxName",

                                       cb3.getId());

}