Modifying Physical Renderer Code for Event Helper

This topic describes how to work with previously customized of physical renderers that deal specifically with event binding. It describes the changes that are required to allow them to work in Siebel Innovation Pack 2014 and later. It contains the following information:

"Binding Stray DOM Events"
"Binding Events for Controls"

Binding Stray DOM Events

In Siebel Innovation Pack 2014 and later, the Event Helper object manages events and their handlers. This object is available as the custom physical renderer for event handler management. You can use the helper object to attach custom event handlers to stray DOM objects. The objects fall into one of the following categories:

DOM Elements Configured in SWE OUI Templates. These are DOM elements configured in the SWE OUI Templates but not in the repository, and are directly addressed and manipulated at the client-level using JavaScript code.
DOM Elements with No Representation. These are DOM elements that have no representation on the server, and are completely constructed and manipulated at the client-level using JavaScript code.

The event helper object can attach and manage event handlers to both types of DOM elements listed above. However, it is essential that any stray binding occurring in the custom renderer code is modified to work with the Event Helper object. The Event Helper object homogenizes events between different platforms and devices, and consequently, bound handlers are consistently run across devices.

Modifications Required for DOM Elements Configured in SWE OUI Templates

You must find and modify the instances of DOM elements configured in SWE OUI templates in your custom physical renderer code. The ID or the name used to find the DOM will have been configured as a placeholder using a SWE OUI Template file.

To bind DOM elements configured in SWE OUI templates

Determine if you have custom physical renderer code similar to the following:
```
CustomPhysicalRenderer.prototype.BindEvents = function(){
$("[id=" + "customdiv" + "]").bind("click", { ctx : this }, function(event){
event.data.ctx.GetPM().OnControlEvent(("DIV_CLOSE"));
});
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
```
This event will be attached to a handler in a custom presentation model using an AttachEventHandler call. The call will then trigger custom functionality when the handler is run. A possible outcome of this handler is to affect a model property, which would subsequently be latched on to by a PM binding in the renderer that would hide or remove the div element.

Modify the code located in Step 1 to resemble the following code:

CustomPhysicalRenderer.prototype.BindEvents = function () {
var closeElement = $("[id=" + "customdiv " + "]"),
eventHelper = SiebelApp.S_App.PluginBuilder.GetHoByName("EventHelper");
if (eventHelper && closeElement.length) {
eventHelper.Manage(closeElement, "click", { ctx: this }, OnClickDiv);
}
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
function OnClickDiv(event) {
event.data.ctx.GetPM().OnControlEvent(consts.get("DIV_CLOSE"));
}

Note:

The code in this example is only meant as a guide.

This click event in this code is attached to the stray DOM element using the Manage API of the Event Helper object. The click is homogenized to work with touch based events on touch based devices. OnClickDiv is the handler that is passed.

For the full list of parameters that the Manage API uses, see Appendix A, "Application Programming Interface."

Modifications Required for DOM Elements with No Representation

For DOM elements with no representation, you must find and modify these instances your custom physical renderer for code. These are typically found where the DOM is being created and objects are being attached. This will usually have no representation anywhere in the SWE server.

To bind DOM elements with no representation

Determine if you have custom physical renderer code similar to the following:
```
CustomPhysicalRenderer.prototype.ShowUI = function () {
var clientHTML = "<div id='moreinfo'>Click here for more information about Customer Types</div>",
appletContainer = this.GetPM().Get("GetFullId");
$("#" + appletContainer).append(clientHTML);
SiebelAppFacade.CustomPhysicalRenderer.superclass.ShowUI.call(this);
};
CustomPhysicalRenderer.prototype.BindEvents = function(){
$("[id=" + "moreinfo" + "]").bind("mouseover", { ctx : this }, function(event){
vent.data.ctx.GetPM().OnControlEvent("MORE_INFO");
});
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
```
The first section of the code creates a client side piece of the DOM which is appended to the end of the applet container in the ShowUI section of the custom renderer. The BindEvents section is then overridden to attach a custom event handler to the DOM element.

The second section of the code is an event that will be attached to a custom presentation model using an AttachEventHandler call. The call will then trigger custom functionality when the handler is run. This will display a dialog containing additional information about the contextual record.

Modify the code located in Step1 to resemble the following code:

CustomPhysicalRenderer.prototype.BindEvents = function () {
var moreInfoElement = $("[id=" + "moreinfo" + "]"),
eventHelper = SiebelApp.S_App.PluginBuilder.GetHoByName("EventHelper");
if (eventHelper && moreInfoElement.length) {
eventHelper.Manage(moreInfoElement, "mouseover", { ctx: this }, OnClickMoreInfo);
}
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
function OnClickMoreInfo(event) {
event.data.ctx.GetPM().OnControlEvent("MORE_INFO");
}

Note:

The code in this example is only meant as a guide.

The mouseover event is attached to the stray DOM element that has been created in ShowUI using the Manage API of the Event Helper object. Mouseover is homogenized to work with touch based events on touch based devices, if available.

Binding Events for Controls

This topic describes how to bind events for controls. Similarly to stray DOM event binding, any renderer code that bound events on to existing repository based controls will now have to work with the Event Helper object to bind handlers to controls instead of direct jQuery calls, which is necessary to homogenize events bound to controls across different platforms.

To bind control events

Determine if you have custom renderer code that contains control event binding of the following types:
```
CustomPhysicalRenderer.prototype.BindEvents = function () {
var controlSet = this.GetPM().Get("GetControls");
for (var controlName in controlSet) {
if (controlSet.hasOwnProperty(controlName)) {
var control = controlSet[controlName];
if (control.GetName() === "Probability") {
$('[name="' + control.GetInputName() + '"]').on("click", { ctx: this }, function () {
event.data.ctx.GetPM().OnControlEvent(("PROBABLITY_CLICK"));
});
}
}
}
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
```
In the above code, the complete set of controls is obtained from the framework PM property and the render is looping through set. Upon encountering a particular control by the repository name Probability, a click event handler is being bound to the DOM element representing that control which then triggers the event PROBABILITY_CLICK on to the PM. Eventually, a custom handler is attached as a customized presentation model using the AttachEventHandler API.

Modify the code located in Step 1 to resemble the following code:

CustomPhysicalRenderer.prototype.BindEvents = function () {
var eventHelper = SiebelApp.S_App.PluginBuilder.GetHoByName("EventHelper"),
controlSet = this.GetPM().Get("GetControls"),
controlEl = null;

for (var controlName in controlSet) {
if (controlSet.hasOwnProperty(controlName)) {
var control = controlSet[controlName];
if (control.GetName === "Probability") {
controlEl = this.GetUIWrapper(control).GetEl();
if (controlEl.length && eventHelper) {
eventHelper.Manage(controlEl, "click", { ctx: this }, OnClickProbability);
}
}
}
}
SiebelAppFacade.CustomPhysicalRenderer.superclass.BindEvents.call(this);
};
function OnClickProbablility(){
event.data.ctx.GetPM().OnControlEvent(("PROBABLITY_CLICK"));
}

Note:

The code in this example is only meant as a guide.

In this new code, if the correct control is found using the matching condition, first, the control's element is obtained using the GetEl() API of the control's wrapper. This is subsequently used in the Manage() API of the Event Helper to attach a homogenized click handler on to the DOM element of the control. The named method OnClickProbability is triggered when the event occurs on the control.