12Post-Upgrade Configuration Tasks

Post-Upgrade Configuration Tasks

This chapter describes post-upgrade configuration tasks. Depending on the customization of your deployment, these tasks might be required after upgrading to Siebel Innovation Pack. This appendix includes the following topics:

• Updating Physical Renderer Customizations for Controls

• Modifying Physical Renderer Code for Event Helper

• Overriding Plug-In Wrappers

Updating Physical Renderer Customizations for Controls

This topic describes how to work with existing customizations of physical renderers. It contains the following information:

• Control DOM Access and Changes

• Control Value Access and Changes

• Control State Manipulation

Control DOM Access and Changes

Beginning in Siebel Innovation Pack 2014, Siebel Open UI uses plug-in wrappers to oversee controls and their Document Object Model (DOM) manipulations. Any renderer code required to work with control level DOM elements defers to its respective control plug-in wrapper interface to get the DOM representation.

Any changes required to the DOM will need to be completed by way of the control plug-in wrapper interface. The renderer should not make the changes in itself. The plug-in wrapper should be decorated with the ability to do what is required on the physical UI based on the logical control that it is representing.

To adhere to the conventions used in Siebel Innovation Pack 2014 and later, you need to determine if you have code that needs to be modified. To do this you must find the control DOM access with specific types in your custom renderer code, and replace that code with new code.

To find and modify the control DOM access types in your custom renderer code

1. Determine if you have code that needs to be modified by searching for calls similar to either of the following code samples:

   • var controElement = $('[name="' + control.GetInputName() + '"]');

   • var controElement = $('#' + control.GetInputName());

     Note: Access is not limited to these calls. Similar types of calls that attempt to find the DOM element using the control object should also be replaced.

2. Replace all instances of calls similar to code discovered in Step 1 using following convention:

   var controElement = this.GetUIWrapper(control).GetEl();
   

   These modifications help ensure that the correct jQuery element representing the control on the UI is retrieved, irrespective of the type of renderer from which the call is being made.

GetUIWrapper is a plug-in builder API that is injected into all physical renderers. It returns the plug-in wrapper of the control object that is passed to it. There are various APIs, such as GetEl(), that are executable in the wrapper. For more information about these plug-in wrappers, see Plug-in Wrapper Class.

Control Value Access and Changes

Beginning in Siebel Innovation Pack 2014, Siebel Open UI requires that renderer code that retrieves and sets control values from the DOM consults with the plug-in wrapper interface of the control. Any changes required to the DOM will need to be completed by way of the control plug-in wrapper interface.

Any changes required to the value of the controls will need to be completed by way of the control plug-in wrapper interface. The renderer should not make the changes in itself. The plug-in wrapper should be decorated with the ability to do what is required on the physical UI based on the logical control that it is representing. Wrapper methods can further be customized to decorate on top of these values if required.

To adhere to the conventions used in Siebel Innovation Pack 2014 and later, you need to determine if you have code that needs to be modified. To do this you must find the control value access with specific types in your custom renderer code, and replace that code with new code.

To find and modify the control value access types in your custom renderer code

1. Determine if you have code that needs to be modified by searching for calls similar to either of the following code samples:

   • var value = $('[name="' + control.GetInputName() + '"]').val();

   • var value = $('#' + control.GetInputName()).attr('val');

   Note: Access is not limited to these calls. Similar types of calls that attempt to find the DOM element using the control object should also be replaced.

2. Replace all instances of calls similar to code discovered in Step 1 using following convention:

   var value = this.GetUIWrapper(control).GetValue();
   

   These modifications help ensure that the correct jQuery element representing the control on the UI is retrieved, irrespective of the type of renderer from which the call is being made.

   GetValue() is the plug-in wrapper API that is responsible for getting the DOM value of the control. Similar to this explanation, this change will first fetch the correct wrapper for the control in question and then executes the GetValue API

3. Determine if you have code that needs to be modified by searching for calls similar to either of the following code samples:

   • $('[name="' + control.GetInputName() + '"]').val(newValue);

   • $('#' + control.GetInputName()).attr('val', newValue);

   Note: Access is not limited to these calls. Similar types of calls that attempt to find the DOM element using the control object should also be replaced.

4. Replace all instances of calls similar to code discovered in Step 3 using following convention:

   this.GetUIWrapper(control).SetValue(value, index);
   

   Note: The value set affects neither the client record set nor the server data, unless explicitly committed.

5. (Optional) Other customizations might be necessary if you are using a custom plug-in wrapper that overrides the base wrapper's API which may affect the value before setting it on the DOM. The following is an example of such a customization:

   CustomPW.prototype.SetValue = function (value, index) {   
   value = value + "_suffix";   
   SiebelAppFacade.CustomPW.superclass.SetValue.call(this, value, index);   
   }
   

Control State Manipulation

Beginning in Siebel Innovation Pack 2014, the manipulation of the DOM state of a control occurs in a single call in the control’s wrapper element using the SetState API. Previously this type of manipulation could have been done in many different ways, therefore any custom renderer code must be located and modified.

To find and modify the control state manipulations in your custom renderer code

1. Determine if you have code similar to the following:

   $('[name="' + control.GetInputName() + '"]').hide();
   

2. Replace all instances of calls similar to code discovered in Step 1 by a call to the control's plug-in wrapper that internally affects the state of the element and hides it. Use the following code as guidance:

   this.GetUIWrapper(control).SetState(consts.get("SHOW"), false);
   

3. Determine if you have code similar to the following:

   $('[name="' + control.GetInputName() + '"]').attr("readOnly", "readOnly");
   

   The code here, is a case where a particular control is being made non-editable on the DOM.

4. Replace all instances of calls similar to code discovered in Step 3 using following convention:

   this.GetUIWrapper(control).SetState(consts.get("EDITABLE"), false);
   

5. Determine if you have code similar to the following:

   $('[name="' + control.GetInputName() + '"]').focus();
   

   The code here, is a case where there is an attempt to set focus on a particular control.

6. Replace all instances of calls similar to code discovered in Step 5 using following convention:

   this.GetUIWrapper(control).SetState(consts.get("FOCUS"), true);
   

The SetState API exists in the prototype space of the plug-in wrapper and can also be overridden in a custom plug-in wrapper to be used to affect the functionality of setting states on the control.

For more information about state modification, including parameters accepted by SetState, and the modifications made to the control element, see Architecture of Siebel Open UI and Application Programming Interface.

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 previously listed. 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

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

1. 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.

2. 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 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

1. 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.

2. Modify the code located in Step 1 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

1. 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 this 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.

2. 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"));   
   }
   

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.

Overriding Plug-In Wrappers

This topic describes how to create and apply plug-in wrappers for customization of control appearance and behavior. It contains the following information:

• About Overriding Plug-In Wrappers

• Overview of the Skeleton Structure of a Plug-in Wrapper

• About Presentation Model-Injected APIs in Plug-in Wrappers

About Overriding Plug-In Wrappers

In Siebel Innovation Pack 2014, plug-in wrappers have been introduced to provide an effective manner in which control objects can be customized. Plug-in wrappers effectively manage the entire life cycle of an individual control, including but not limited to its DOM creation, appearance, behaviors and states. For more information about plug-in wrappers, see About Plug-in Wrappers.

Prior to Siebel Innovation Pack 2014, physical renderers were responsible for control behavior. This meant that control representation and its lifecycle were tightly coupled with the physical renderer in which it was hosted. The introduction of plug-in wrappers decouples the control representation and its lifecycle.

Consequently, the physical renderer is no longer aware of the type of controls it needs to deal with, but rather talks to the plug-in wrapper of the control(s) that it hosts. The actual action will take place inside the plug-in wrapper. The result is that the plug-in wrapper is not bound to any particular applet or its physical renderer.

The topics that follow describe how to override plug-in wrappers. For more information about the API specification and the inheritance hierarchy of the plug-in wrappers, see Architecture of Siebel Open UI.

Overview of the Skeleton Structure of a Plug-in Wrapper

This topic describes the skeleton structure of a plug-in wrapper.

In releases previous to Siebel Innovation Pack 2014, you may have customized Siebel Open UI to control behavior in physical renderers. This type of customization will now need to be moved into custom plugin wrappers. The skeleton structure in this topic provides a broad overview of what parts of a plug-in wrapper you will need to customize to achieve parity with your previous customizations.

The following figure illustrates the basic structure of the code you use to override a plug-in wrapper. The example code, would be contained in an independent file in the following directory:

INSTALL_DIR\applicationcontainer\webapps\siebel\scripts\siebel\custom

For information about deployment and manifest configuration, see Example of Customizing Siebel Open UI.

Explanation of Callouts

1. Definition of the Custom Plug-In Wrapper. Defines a custom wrapper by following the same ideology as presentation models and physical renderers. It lists the file of the wrapper and lists the dependencies. This will act as a module identifier to the RequireJS plug-in that Siebel Open UI uses to manage all client side modules.

   Note: Controls that use third-party files list the dependencies here. They must be moved out of the renderer that listed this external dependency.

2. Constructor. Does the required changes and calls the superclass. The choice of class from which to extend is decided in this section. It can be a new plug-in wrapper, or subset deviation from an existing plug-in wrapper.

3. Lifecycle Methods. Specifies the methods that have been overridden. There is no need to override methods that have not been customized, because the superclass method will be called in instead. Here are the methods that are overridden in this example:

   • ShowUI. Override this method to modify display level changes to the control. You can create new DOM or modify an existing DOM that is created by the superclass.

   • BindEvents. Override this method to customize event handlers for the control. You can create new handlers in addition to those being added by the superclass or create an entirely different set by not calling the BindEvents in the superclass.

   • SetValue. Override this method to affect any value changes to the control. Decorate the exiting value display mechanism or change it completely by avoiding the call to the superclass.

   • SetState. Override this method to affect any state changes to the control. Control the behavior when changes to the state; such as editability, focus, and others; are requested. One or more states can be affected by controlling calls to the superclass.

4. Private Methods. Use private methods like in presentation models and physical renderers to handle custom functionality, for example: Event Handler definitions.

5. Declaration of Custom Plug-in Wrappers. This is the section that declares to the framework that a custom plug-in wrapper has been deployed. It describes the conditions under which the plug-in wrapper needs to be used. Its parameters are:

   • Control Type. The SWE constant for the type of control for which the functionality is trying to be overridden.

   • PW Class. The class name of the custom plug-in wrapper.

   Return Conditions. This describes the conditions under which the extended plug-in wrapper should be used. A return of true will attach the extension.

   • Control Object. The instance of the control object for which the decision needs to be made. All control object APIs are available here. Use this object and its APIs to evaluate the return value to true for the specific control or controls for which the extension needs to be applicable.

   • objName. The name of the object, applet or view for which the decision needs to be made. Use this to evaluate the return value to true for the specific applet for which the extension needs to be applicable.

About Presentation Model-Injected APIs in Plug-in Wrappers

This topic includes information about presentation model-injected APIs in plug-in wrappers.

You can use the APIs in this topic to achieve the customized functionality you were using previously in renderers. The code examples for each of the methods in this topic can be used as references about achieving the same or similar customizations in Siebel Innovation Pack 2014.

For more information about plug-in wrappers, examples of configuration and further information about APIs, see Architecture of Siebel Open UI, Example of Customizing Siebel Open UI and Application Programming Interface

While the following APIs have been described earlier in this documentation in the context of use within the physical renderer to act as liaisons with the plug-in wrapper, they are also available for use from within the plug-in wrapper:

• GetEl. Used to get the DOM (jQuery element) that represents the control.

• GetValue. Used to access the DOM value of the control.

• SetValue. Used to set the DOM value of the control.

• SetState. Used to set various DOM states for the control.

In addition to the APIs listed here, the framework injects certain presentation model-level APIs into all plug-in wrappers to ease the layering of calls that a plug-in wrapper is required to complete. This makes programming in customized plug-in wrappers very similar to programming customized physical renderers. These types of APIs are described in the following topics.

Get

This API gets the value of a PM property where the control is deployed.

SetProperty

This API allows the plug-in wrapper set a property on the PM on which this control is operating. They are PM properties that the plug-in wrapper is acting on.

The following example shows how a CustomPW can operate on a PM property, and how another CustomPW can subsequently use the property for other purposes:

CustomPW1.prototype.ShowUI = function (control) {   
// Custom Show Definition   
if (this.Get("ShowControl1") === true) {   
SiebelAppFacade.CustomPW1.superclass.BindEvents.call(this);   
}   
this.SetProperty("ShowControl2", false);   
}   
 CustomPW2.prototype.ShowUI = function (control) {   
// Custom Show Definition   
if (this.Get("ShowControl2") === true) {   
SiebelAppFacade.CustomPW2.superclass.BindEvents.call(this);   
}   
}

ExecuteMethod

This API is similar to the ExecuteMethod in the presentation model: it allows the plug-in wrapper to execute a method on the PM on which it is operating.

OnControlEvent

This API runs the event handler call up to the presentation model and subsequently any custom event handlers that may be attached to the event.

The following example shows the usage of APIs in a custom event handler on a custom plug-in wrapper. It depicts a method that is executed on the presentation model, the return value determines if the event should be handled or ignored:

function OnClick(evt) {   
// This is a custom click handler for my control.   
var self = evt.data.ctx,   
shouldHonorClick = self.ExecuteMethod("CustomPMMethod");   
if (shouldHonorClick) {   
 self.OnControlEvent("customClickEvent", self.control, self.dataset);   
}   
}

Helper

This API is used to obtain helper objects from the plug-in wrapper. Currently only the EventHelper object is present. Any control level custom binding should happen using this helper object.

The following example binds two events on to the control in the customized wrapper, and runs custom handlers defined in the wrapper:

CustomPW.prototype.BindEvents = function (control) {   
var ele = this.GetEl(),   
evHelper = this.Helper("EventHelper");   
evHelper   
.Manage(ele, "click", { ctx: this }, OnClick)   
.Manage(ele.next("span"), "hover", { ctx: this }, OpenAlertBox);   
};   
function OnClick() {   
// Custom Definition for element click here   
}   
function OpenAlertBox() {   
// Custom Definition for element next span hover here   
}

For a detailed example about using APIs in a customized wrapper, see Configuring the Manifest for the Color Box Example.