Customizing Controls

This topic describes how to customize a control. It includes the following information:

"Creating and Managing Client-Side Controls"
"Displaying Control Labels in Different Languages"

This book includes a number of other topics that also customize controls. For more information about:

Overview information about customizing controls, see "How Siebel CRM Renders High-Interactivity Clients", "Examples of How You Can Customize Siebel Open UI", "Example Client Customizations", and "Guidelines for Customizing Siebel Open UI"
Adding a control to a presentation model, see "Customizing the Setup Logic of the Presentation Model"
Modifying a list column control so that Siebel Open UI stores the value of the control check box, see "Customizing the Presentation Model to Identify the Records to Delete"
Customizing control user properties, see "Customizing Control User Properties for Presentation Models"
Accessing a proxy object for an active control, see "Accessing Proxy Objects"
Customizing control themes, see "Customizing Themes for Other Objects"
Rendering controls according to control type, see "Customizing List Applets to Render as Maps"
Adding a control that does a static drill-down, see "Adding Static Drilldowns to Applets"
Customizing controls in an applet, see "Customizing Applets to Capture Signatures from Desktop Applications"
Adding controls to the calendar, "Customizing a Resource Scheduler"

Creating and Managing Client-Side Controls

The example in this topic describes how to create a text box that the Siebel Open UI client displays, and is not represented on the Siebel server. This is a Siebel Open UI client implementation, and as such, data will not be maintained after the user navigates away from the view containing this type of control. You can also create similar controls, such as date/time, checkbox, combobox, and so on.

This example shows how to configure client-side controls in list applets, however, the same principals can be applied to form applets.

To create controls in the client

Create a custom presentation model:

Use a JavaScript editor to create a new file named clientctrlpmodel.js . Save this file in the following folder:
```
siebel\custom
```
For more information about:
- The complete presentation model that this example uses, see "Text Copy of the Client Control Presentation Model File".
- This folder, see "Organizing Files That You Customize".

Add the following code to the file that you created in Step a.

This code does the basic set up:

if( typeof( SiebelAppFacade.ClientCtrlPModel ) === "undefined" ){
  SiebelJS.Namespace( 'SiebelAppFacade.ClientCtrlPModel' );
  //Module with its dependencies
  define("siebel/custom/clientctrlpmodel", [], function () {
  SiebelAppFacade.ClientCtrlPModel = ( function(){
    var consts  = SiebelJS.Dependency( "SiebelApp.Constants" );
    /* *
    * Constructor Function - ClientCtrlPModel
    *
    * Parameter - Be a good citizen. Pass All parameter to superclass.
    * */
    function ClientCtrlPModel(proxy){
      var m_recordset = [];
      SiebelAppFacade.ClientCtrlPModel.superclass.constructor.call( this, proxy);

Add the client control:

      this.AddMethod("AddClientControl", null, { core : true } );
      // add into method array
      this.GetClientRecordSet = function( ) {
        return m_recordset ;
      };
    }

For more information, see "AddMethod Method" and "AddClientControl Method".

Extend the ListPresentationModel object:

    /* Siebel OpenUI uses the ListPresentationModel object to initialize every list applet. So, to maintain the functionality that ListPresentationModel provides, you extend it.*/
    SiebelJS.Extend( ClientCtrlPModel, SiebelAppFacade.ListPresentationModel );
    ClientCtrlPModel.prototype.Init = function(){
      SiebelAppFacade.ClientCtrlPModel.superclass.Init.call( this );

Determine whether or not Siebel Open UI has removed the focus from the field in the applet, and then temporarily store the value that the user entered in the control:
```
      /* Attach Post Handler for LeaveField */
      this.AddMethod( "LeaveField", PostLeaveField, { sequence : false, scope : this } );
```
For more information, see "LeaveField Method" and "PreGetFormattedFieldValue Method".

Get the format that the field uses to store the value for the control:

      /* Attach Pre Handler for GetFormattedFieldValue */
      this.AddMethod("GetFormattedFieldValue", PreGetFormattedFieldValue, { sequence : true, scope : this } );
      /* Attach Handler for Delete Record Notification as well */
      this.AttachNotificationHandler( consts.get( "SWE_PROP_BC_NOTI_DELETE_RECORD" ),       HandleDeleteNotification );

For more information, see "GetFormattedFieldValue Method".

Get the data from memory stored in f, and then display this data in the client control:

function PreGetFormattedFieldValue(control, bUseWS, recIndex, returnStructure){
  if (utils.IsEmpty(recIndex)){
    recIndex = this.Get("GetSelection");
  }
  if (recIndex >=0) {
    var clientObj = this.GetClientRecordSet();
    var recordSet=this.Get("GetRawRecordSet");
    var id = recordSet[recIndex]["Id"];
    var flag = false;
    var value;
    switch(control.GetName()){
      case "TestEdit":
        value = recordSet[recIndex]["Name"];
        flag = true;
        break;
    }
    if (flag){
      if( clientObj[id] && clientObj[id][control.GetName()] ){
        value = clientObj[id][control.GetName()];
      }
      else if (clientObj[id]){
        clientObj[id ][control.GetName()] = value;
      }
    else{
        var recordclient = {};
        recordclient[control.GetName()] = value;
        clientObj[id] = recordclient;
      }
      returnStructure[ "CancelOperation" ] = true;
      returnStructure[ "ReturnValue" ]     = value;
    }
  }
}

For more information, see "PreGetFormattedFieldValue Method".

Save the value after the user leaves the client control:

function PostLeaveField( control, value, notLeave, returnStructure ){
  var clientObj = this.GetClientRecordSet();
  var currSel = this.Get( "GetSelection" );
  var recordSet=this.Get("GetRawRecordSet");
  var id = recordSet[currSel]["Id"];
  if (clientObj[id]){
    switch(control.GetName()){
      case "TestEdit":
        clientObj[id][control.GetName()] = returnStructure[ "ReturnValue" ] ;
        break;
    }
  }
}

For more information, see "PreGetFormattedFieldValue Method".

Delete the reference to the record data that Siebel Open UI stored in the client for the control:

    function HandleDeleteNotification(propSet){
      var activeRow = propSet.GetProperty( consts.get( "SWE_PROP_BC_NOTI_ACTIVE_ROW" ) );
      if( activeRow  === this.Get( "GetSelection" ) ){
        var delObj = this.GetClientRecordSet();
        delObj[ activeRow ] = null;
      }
    }

For more information, see "HandleDeleteNotification Method".

Create a property set for the control.

For this example, you use the following code to create a property set for the text box control:

    ClientCtrlPModel.prototype.UpdateModel = function(psInfo){
    /// Specify the property set for Edit box
    SiebelAppFacade.ClientCtrlPModel.superclass.UpdateModel.call( this, psInfo );
    var ctrlTxtInfo = SiebelAppFacade.PresentationModel.GetCtrlTemplate ("TestEdit", "Test Edit", consts.get( "SWE_CTRL_TEXTAREA" ), 1);

For more information about this code, see "Creating Property Sets for Client- Side Controls".

Add the property set information so that Siebel Open UI can add it to the proxy:
```
this.ExecuteMethod( "AddClientControl", ctrlTxtInfo );
```

Return the ClientCtrlPModel that you set up in Step b:

    };
    return ClientCtrlPModel;
    } ());
    return "SiebelAppFacade.ClientCtrlPModel";
  });
}

Configure the manifest:
1. Log in to a Siebel client with administrative privileges.
2. Navigate to the Administration - Application screen, and then the Manifest Files view.
3. In the Files list, add the following new files.
  
  Field Value
  
  Name siebel/custom/clientctrlpmodel.js
4. Navigate to the Administration - Application screen, and then the Manifest Administration view.
5. In the UI Objects list, specify the following applet.
  
  Field Value
  
  Type Applet
  
  Usage Type Presentation Model
  
  Name Account List Applet
6. In the Object Expression list, add the following expression. The physical renderer uses this expression to render the applet in a desktop platform.
  
  Field Value
  
  Expression Desktop
  
  Level 1
7. In the Files list, add the following file:
```
siebel/custom/clientctrlpmodel.js
```
8. To refresh the manifest, log out of the client, and then log back in to the client.
Test your work:
1. Navigate to any list applet, and then verify that it displays the control that you added.
  
  In Step 1b, you extended the ListPresentationModel object that Siebel Open UI uses to display every list applet. So, you can navigate to any list applet.

Field	Value
Name	siebel/custom/clientctrlpmodel.js

Field	Value
Type	Applet
Usage Type	Presentation Model
Name	Account List Applet

Field	Value
Expression	Desktop
Level	1

Creating Property Sets for Client- Side Controls

You can use the following code to create a property set for a control that Siebel Open UI displays in the client:

ClientCtrlPModel.prototype.UpdateModel = function(psInfo){
/// Specify the property set for the control
SiebelAppFacade.ClientCtrlPModel.superclass.UpdateModel.call( this, psInfo );
var variable_name= SiebelAppFacade.PresentationModel.GetCtrlTemplate
  ("control_name", "display_name", consts.get( "control_type" ), column_index );
    ctrlComboInfo.SetPropertyStr(consts.get("control_property"), "property_attribute")

where:

control_name, display_name, control_type, and column_index are arguments of the GetCtrlTemplate method. For more information about these arguments, see "GetCtrlTemplate Method".
control_property specifies a control property. For example, SWE_PROP_WIDTH specifies the width of the control, in pixels.
property_attribute specifies an attribute of the control that control_property specifies. For example, 200 sets the width of the control to 200 pixels.

For example, the following code creates a variable named ctrlComboInfo for the TestCombo control. It sets the width and height of this control to 200 pixels, and centers it

ClientCtrlPModel.prototype.UpdateModel = function(psInfo){
/// Specify the property set for the control
SiebelAppFacade.ClientCtrlPModel.superclass.UpdateModel.call( this, psInfo );
ClientCtrlPModel.prototype.UpdateModel = function(psInfo){
/// Specify the property set for the control
SiebelAppFacade.ClientCtrlPModel.superclass.UpdateModel.call( this, psInfo );
var ctrlComboInfo = SiebelAppFacade.PresentationModel.GetCtrlTemplate ("TestCombo",
  "Test Drop Down", consts.get( "SWE_CTRL_COMBOBOX" ), 10 );
    ctrlComboInfo.SetPropertyStr(consts.get("SWE_PROP_WIDTH"), "200")
    ctrlComboInfo.SetPropertyStr(consts.get("SWE_PROP_HEIGHT"), "200")
    ctrlChkboxInfo.SetPropertyStr(consts.get("SWE_PROP_JUSTIFICATION"), "center");

For more information about control_property and property_attribute, see "Properties That You Can Specify for Client-Side Controls". For more information about other control properties that you can specify, such as Sort or Vertical Scroll, see the topic that describes the control Applet Object Type in Siebel Object Types Reference.

Properties That You Can Specify for Client-Side Controls

Table 6-2 describes the properties that you can specify for controls. The Comparable Applet Control or Description column of this table includes the name of the applet control property that is similar to the SWE control property. If no applet control property is similar to the SWE control property, then this column includes a description. For more information about these applet control properties, see the topic that describes controls in the applet object types section of Siebel Object Types Reference.

Table 6-2 Properties That You Can Specify for Controls

SWE Control Property	Comparable Applet Control or Description
SWE_PROP_CURR_FLD	Identifies the field that is currently chosen.
SWE_PROP_CASE_SENSITIVE	Specifies to make text in the control case-sensitive.
SWE_PROP_DISP_FORMAT	Display Format
SWE_PROP_DISP_MODE	HTML Display Mode
SWE_PROP_DISP_MAX_CHARS	HTML Max Chars Displayed
SWE_PROP_DISP_NAME	Specifies the label that Siebel Open UI uses to identify this control in the client.
SWE_PROP_FLD_NAME	Field Name
SWE_PROP_HEIGHT	HTML Height
SWE_PROP_HTML_ATTRIBUTE	HTML Attributes
SWE_PROP_IS_BOUND_PICK	Specifies that the control is a bound picklist.
SWE_PROP_IS_ENCODE	HTML Display Mode
SWE_PROP_INPUTMETHOD	MethodInvoked
SWE_PROP_JUSTIFICATION	Text Alignment
SWE_PROP_LABEL_JUSTIFICATION	Specifies the text alignment for a column header that Siebel Open UI displays in a list control.
SWE_PROP_MAX_SIZE	HTML Max Chars Displayed
SWE_PROP_NAME	Name
SWE_PROP_PICK_APLT	Pick Applet
SWE_PROP_POPUP_HEIGHT	Specifies the height of the popup dialog box, in pixels.
SWE_PROP_PROMPT	Prompt Text
SWE_PROP_POPUP_WIDTH	Specifies the width of the popup dialog box, in pixels.
SWE_PROP_IS_DYNAMIC	Specifies whether or not Siebel Open UI dynamically displays values in the control.
SWE_PROP_SPAN	Specifies to span control contents across multiple fields. This property is not applicable for list controls.
SWE_PROP_SEQ	HTML Sequence
SWE_PROP_TYPE	Type, HTML Type, or Field Retrieval Type
SWE_PROP_WIDTH	Width
SWE_PROP_COLINDEX	Specifies the index number of a column.
SWE_PROP_ICON_MAP	Bitmap
SWE_PROP_IS_SORTABLE	Sort

Text Copy of the Client Control Presentation Model File

The following code from the clientctrlpmodel.js file adds example controls to the client. You can examine this code for your reference. To get a copy of this file, see Article ID 1494998.1 on My Oracle Support:

if( typeof( SiebelAppFacade.ClientCtrlPModel ) === "undefined" ){
  SiebelJS.Namespace( 'SiebelAppFacade.ClientCtrlPModel' );
  //Module with its dependencies
  define("siebel/custom/clientctrlpmodel", [], function () {
  SiebelAppFacade.ClientCtrlPModel = ( function(){
    var consts  = SiebelJS.Dependency( "SiebelApp.Constants" );
    /* *
    * Constructor Function - ClientCtrlPModel
    *
    * Parameter - Be a good citizen. Pass All parameter to superclass.
    * */
    function ClientCtrlPModel(proxy){
      var m_recordset = [];
      SiebelAppFacade.ClientCtrlPModel.superclass.constructor.call( this, proxy);
      this.AddMethod( "AddClientControl", null, { core : true } );
      // add into method array
      this.GetClientRecordSet = function( ) {
        return m_recordset ;
      };
    }
    /* Siebel OpenUI uses the ListPresentationModel object to initialize every list applet. So, to maintain the functionality that ListPresentationModel provides, you extend it.*/
    SiebelJS.Extend( ClientCtrlPModel, SiebelAppFacade.ListPresentationModel );
    ClientCtrlPModel.prototype.Init = function(){
      SiebelAppFacade.ClientCtrlPModel.superclass.Init.call( this );
      /* Attach Post Handler for LeaveField */
      this.AddMethod( "LeaveField", PostLeaveField, { sequence : false, scope : this } );
      /* Attach Pre Handler for GetFormattedFieldValue */
      this.AddMethod("GetFormattedFieldValue", PreGetFormattedFieldValue, { sequence : true, scope : this } );
      /* Attach Handler for Delete Record Notification as well */
      this.AttachNotificationHandler( consts.get( "SWE_PROP_BC_NOTI_DELETE_RECORD" ),       HandleDeleteNotification );
    };
    function PreGetFormattedFieldValue(control, bUseWS, recIndex, returnStructure){
      if (utils.IsEmpty(recIndex)){
        recIndex = this.Get("GetSelection");
      }
      if (recIndex >=0) {
        var clientObj = this.GetClientRecordSet();
        var recordSet=this.Get("GetRawRecordSet");
        var id = recordSet[recIndex]["Id"];
        var flag = false;
        var value;
        switch(control.GetName()){
          case "TestEdit":
            value = recordSet[recIndex]["Name"];
            flag = true;
            break;
        }
        if (flag){
          if( clientObj[id] && clientObj[id][control.GetName()] ){
            value = clientObj[id][control.GetName()];
          }
          else if (clientObj[id]){
            clientObj[id ][control.GetName()] = value;
          }
        else{
            var recordclient = {};
            recordclient[control.GetName()] = value;
            clientObj[id] = recordclient;
          }
          returnStructure[ "CancelOperation" ] = true;
          returnStructure[ "ReturnValue" ]     = value;
        }
      }
    }
    function PostLeaveField( control, value, notLeave, returnStructure ){
      var clientObj = this.GetClientRecordSet();
      var currSel = this.Get( "GetSelection" );
      var recordSet=this.Get("GetRawRecordSet");
      var id = recordSet[currSel]["Id"];
      if (clientObj[id]){
        switch(control.GetName()){
          case "TestEdit":
            clientObj[id][control.GetName()] = returnStructure[ "ReturnValue" ] ;
            break;
        }
      }
    }
        function HandleDeleteNotification(propSet){
          var activeRow = propSet.GetProperty( consts.get( "SWE_PROP_BC_NOTI_ACTIVE_ROW" ) );
          if( activeRow  === this.Get( "GetSelection" ) ){
            var delObj = this.GetClientRecordSet();
            delObj[ activeRow ] = null;
          }
        }
        ClientCtrlPModel.prototype.UpdateModel = function(psInfo){
        /// PS Attribute info for Edit box
        SiebelAppFacade.ClientCtrlPModel.superclass.UpdateModel.call( this, psInfo );
        var ctrlTxtInfo = SiebelAppFacade.PresentationModel.GetCtrlTemplate ("TestEdit", "Test Edit", consts.get( "SWE_CTRL_TEXTAREA" ), 1);
      this.ExecuteMethod( "AddClientControl", ctrlTxtInfo );
    };
    return ClientCtrlPModel;
  } ());
    return "SiebelAppFacade.ClientCtrlPModel";
  });
}

Configuring Client-Side Multi-Select

Siebel Open UI uses a client-side control implementation to display a Multi-Select checkbox column in list applets. While this is primarily intended for touch-based devices where multiple selection of rows is not possible using the Shift + Click or Ctrl + Click, it can also be configured for desktop browsers.

The Multi Row Select Checkbox Display user property controls the behavior and availability of the client-side multi-select checkboxes. The property can have the following values:

TOUCH-HIDE. The multi-select column does not appear on touch devices.
TOUCH-SHOW. The multi-select column appears on touch devices.
NONTOUCH-HIDE. The multi-select column does not appear on desktop and non-touch based devices.
NONTOUCH-SHOW. The multi-select column appears on desktops and non-touch based Touch devices.

When the user property is not configured for an applet, the default behavior is to show the Multi-Select column on touch devices and hide the column on non-touch devices. Administrators can use the user property to override this behavior on a per-list applet basis.

To configure multi-select checkbox for a list applet

Open Siebel Tools.

For more information, see Using Siebel Tools.
In the Object Explorer, click Applet.
In the Applets list, locate the applet that you want to configure.
Add the applet user property to the applet that you located in Step 3:
1. In the Object Explorer, expand the Applet tree, and then click Applet User Prop.
2. In the Applet User Props list, add the following applet user property with one of the possible values:
  
  Name Values
  
  Multi Row Select Checkbox Display TOUCH-HIDE, TOUCH-SHOW, NONTOUCH-HIDE, NONTOUCH-SHOW
Compile the applet object.
Restart the Siebel server.

Your changes will now be visible in the Siebel Open UI client.

Name	Values
Multi Row Select Checkbox Display	TOUCH-HIDE, TOUCH-SHOW, NONTOUCH-HIDE, NONTOUCH-SHOW

Displaying Control Labels in Different Languages

This topic describes how to modify the custom_messages.js file so that Siebel Open UI displays the text for a control label according to the language that the client browser uses. You can also modify the presentation model instead of modifying the custom_messages.js file. For more information about how to do this, see "Customizing Presentation Models to Display Control Labels in Different Languages". For more information about language support, see "Languages That Siebel Open UI Supports".

To display control labels in different languages

Copy custom_messages.js file from:

INSTALL_DIR\eappweb\PUBLIC\DEU\build_number\scripts\siebel\samples

Save a copy of the file that you copied in Step1, to:

INSTALL_DIR\eappweb\PUBLIC\DEU\build_number\scripts\siebel\custom

Open the file you saved in Step 2 using a JavaScript editor.

Locate the following code:

function _SWEgetGlobalCustomMsgAry()
{
  if (! _SWEbCMsgInit)
  {
    SWEbCMsgInit = true;
  }
  return _SWEcustommsgAry;
}

Add the following bolded code to the code that you located in Step 4:
```
function _SWEgetGlobalCustomMsgAry()
{
  if (! _SWEbCMsgInit)
  {
    SWEbCMsgInit = true;
    SWEcustommsgAry["ID"] = "custom_string";
  }
  return _SWEcustommsgAry;
}
```
where:
- ID is a string that you use to reference the custom_string. You can use any value for ID.
- custom_string is a text string that includes text that you manually translate into the language that your deployment requires.
For example, you can use the following code to convert the text label that Siebel Open UI uses for the New button that it displays on the Contact List Applet to Neu, and the Delete button to Löschen:
```
function _SWEgetGlobalCustomMsgAry()
{
  if (! _SWEbCMsgInit)
  {
    SWEbCMsgInit = true;
    SWEcustommsgAry["New"] = "Neu";
    SWEcustommsgAry["Delete"] = "Löschen";
  }
  return _SWEcustommsgAry;
}
```
Test your work:
1. Navigate to the screen that includes the control that Siebel Open UI uses to display the translated string that you modified in Step 4.
2. Verify that the control displays the translated string.

Customizing Presentation Models to Display Control Labels in Different Languages

This topic describes how to customize a presentation model so that it displays a control label in a different language instead of modifying the custom_messages.js file.

To customize presentation models to display control labels in different languages

Use a JavaScript editor to open the presentation model that Siebel Open UI uses to display the control label that you must modify.

For more information, see "About the Presentation Model".
Add the following code to call the ExecuteMethod method that the presentation model uses. You can add this code anywhere in the presentation model file:
```
pm.ExecuteMethod("AddLocalString","ID","custom_string");
```
where:
- AddLocalString is the name of the method that ExecuteMethod calls to add your custom string.
For more information about how this example uses ID and custom_string, see Step 5 under "Displaying Control Labels in Different Languages". For more information about these methods, see "AddLocalString Method" and "ExecuteMethod Method".

For example, add the following code:
```
pm.ExecuteMethod("AddLocalString", "New", "Neu");
pm.ExecuteMethod("AddLocalString", "Delete", "Löschen");
```
Do Step 6 under "Displaying Control Labels in Different Languages".