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 Chapter 3, "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.

Figure C-1 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\eappweb\PUBLIC\scripts\siebel\custom

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

Figure C-1 Skeleton Structure of the Plug-in Wrapper

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 Chapter 3, "Architecture of Siebel Open UI," Chapter 4, "Example of Customizing Siebel Open UI," and Appendix A, "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 above, 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"

• "SetProperty"

• "ExecuteMethod"

• "OnControlEvent"

• "Helper"

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