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.

In order to adhere to the conventions used in Siebel Innovation Pack 2014, you will 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

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

In order to adhere to the conventions used in Siebel Innovation Pack 2014, you will 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

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.
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 the explanation above, this change will first fetch the correct wrapper for the control in question and then executes the GetValue API
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.
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.
(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. Below 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

Determine if you have code similar to the following:

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

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);
```
Determine if you have code similar to the following:
```
$('[name="' + control.GetInputName() + '"]').attr("readOnly", "readOnly");
```
The code above, is a case where a particular control is being made non-editable on the DOM.
Replace all instances of calls similar to code discovered in Step 3 using following convention:
```
this.GetUIWrapper(control).SetState(consts.get("EDITABLE"), false);
```
Determine if you have code similar to the following:
```
$('[name="' + control.GetInputName() + '"]').focus();
```
The code above, is a case where there is an attempt to set focus on a particular control.
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 Chapter 3, "Architecture of Siebel Open UI," and Appendix A, "Application Programming Interface."