Doing General Customization Tasks

This topic describes some of the general customization tasks that you can do in Siebel Open UI. It includes the following information:

• "Enabling Object Managers for Siebel Open UI"

• "Preparing Siebel Tools to Customize Siebel Open UI"

• "Modifying the Application Configuration File"

• "Deriving Presentation Models, Physical Renderers and Plug-in Wrappers"

• "Adding Presentation Model Properties That Siebel Servers Send to Clients"

• "Configuring Siebel Open UI to Bind Methods"

• "Calling Methods for Applets and Business Services"

• "Using the Base Physical Renderer Class With Nonapplet Objects"

• "Customizing Events"

• "Creating Components"

• "Allowing Users to Interact with Clients During Business Service Calls"

• "Customizing How Siebel Open UI Displays Error Messages"

Enabling Object Managers for Siebel Open UI

You must enable the object manager to use Siebel Open UI before you can do any customization work.

To enable object managers for Siebel Open UI 

1. Enable the object manager for the Siebel Server:

   1. Log in to the Siebel CRM client with administrator privileges.

   2. Navigate to the Administration - Server Configuration screen, and then the Servers view.

   3. In the Components list, query the Component field for the object manager where you must enable Siebel Open UI.

      For example, query for the following value. You must include the double quotes:

      "Call Center Object Manager (ENU)"
      

   4. In the bottom applet, click Parameters.

   5. In the Component Parameters list, query the Parameter field for EnableOpenUI.

   6. Set the Value on Restart field to TRUE.

   7. Log out of the client, and then close the browser.

   As an alternative to using the administrative screens, you can modify the application configuration file on the Siebel Server in the same way that you modify this file on the client in Step 2.

2. Enable Siebel Open UI on the Mobile Web Client:

   1. On the client computer, use a text editor to open the application configuration file.

      For example, to open the configuration file for Siebel Call Center, navigate to the following folder, and then open the uagent.cfg file:

      client_install_location\bin
      

   2. In the InfraUIFramework section, set the EnableOpenUI parameter to the following value:

      [InfraUIFramework]
      EnableOpenUI=TRUE
      

   3. Save, and then close the application configuration file.

   4. Log in to Siebel Call Center, and then verify that it opens the Siebel Open UI client.

      To revert to the high-interactivity client, you can set the EnableOpenUI parameter to FALSE. If you do this reversion, then you must use Internet Explorer, version 8 or earlier when you open the client.

3. Stop the Siebel Server:

   1. On the computer where the Siebel Server resides, click the Start menu, Control Panel, Administrative Tools, and then the Services menu item.

   2. In the Services dialog box, right-click the Siebel Server service, and then click Stop.

   3. Wait for the Siebel Server to stop.

4. Optional. Add object managers for Siebel Mobile:

   1. Stop the Gateway Server, and then make a backup copy of the siebns.dat file.

   2. Restart the Gateway Server.

   3. Open a command line window and set the SIEBEL_HOME environment variable to the following folder:

      SES_HOME/siebsrvr
      

   4. Navigate to the following folder:

      SES_HOME/siebsrvr/bin/language_code
      

      For more information about the language_code, see "Languages That Siebel Open UI Supports".

   5. Run the create_compdef_sia.ksh script or the create_compdef_sia.bat file. Use the following parameters:

      ./create_compdef_sia.ksh GATEWAY:port_number ENTERPRISE user_name user_password language_code
      

   6. Examine the srvrcfg log files, and then make sure Siebel CRM did not log any errors when it enabled the new server components.

   7. Open the Server Manager, and then run the following commands:

      enable compgrp HandheldSync for server server_name
      enable compgrp HandheldSyncSIS for server server_name
      

5. Start the Siebel Server:

   1. Click the Start menu, Control Panel, Administrative Tools, and then the Services menu item.

   2. In the Services dialog box, right-click the Siebel Server service, and then click Start.

   3. Wait for the server to start.

   4. Optional. Make sure the server components you enabled in Step 4g are on line.

6. Optional. Add virtual directories for Siebel Mobile object managers:

   1. Use Windows Explorer to navigate to the following folder:

      INSTALL_DIR\eappweb\bin\
      

   2. Create a back up copy of each of the following files:

      • eapp.cfg.

      • eapps_sia.cfg.

      • Web server configuration files. For example, obj.conf, httpd.conf, and so on.

   3. Stop the HTTP server.

   4. Open a command line window and navigate to the following folder:

      INSTALL_DIR/eappweb/config
      

   5. Run the new_virdirs.bat script or the new_virdirs.sh script. Use values from the following table:

      Operating System	Command
      Windows	Run the following command: new_virdirs.bat language_code
      Unix	Run the following command: newvirdirs.sh languages web_server where: languages is a list of language codes where a comma separates each code web_server identifies the folder where the Web server resides

      
      

   6. If the script fails to run correctly, then you must restore all files from the backup copies you made in b, and then run the script again until it successfully finishes.

   7. Restart the HTTP Server.

   8. Make sure you can use the URL to access the new server components.

7. Log in to the Siebel CRM client and make sure it displays the Siebel Open UI client.

How Siebel Open UI Loads the Siebel Application Depending on How You Set the EnableOpenUI Parameter

Table 5-1 describes how Siebel Open UI loads a Siebel application differently depending on how you set the EnableOpenUI parameter.

Table 5-1 How Siebel Open UI Loads the Siebel Application Depending on How You Set the EnableOpenUI Parameter

EnableOpenUI Setting	Description
EnableOpenUI=FALSE	If you: Customized the default Siebel Web Template, then Siebel Open UI loads the application from the following folder: siebsrvr\webtempl\custom Did not customize the default Siebel Web Template, then Siebel Open UI finds no file in the siebsrvr\webtempl\custom folder, and it loads the Siebel application from the following default folder: siebsrvr\webtempl
EnableOpenUI=TRUE	If you: Customized the Siebel Open UI Siebel Web Template, then Siebel Open UI loads the Siebel application from the following folder: siebsrvr\webtempl\ouiwebtempl\custom Did not customize the Siebel Open UI Siebel Web Template, then Siebel Open UI finds no file in the siebsrvr\webtempl\ouiwebtempl\custom folder, and it loads the Siebel application from the following folder: siebsrvr\webtempl\ouiwebtempl If Siebel Open UI does not find a file in the siebsrvr\webtempl\ouiwebtempl folder, then it loads the Siebel application from the following default folder: siebsrvr\webtempl

Preparing Siebel Tools to Customize Siebel Open UI

This topic describes how to prepare Siebel Tools so that you can use it to customize Siebel Open UI. For more information, see Using Siebel Tools.

To prepare Siebel Tools to customize Siebel Open UI 

1. Add the EnableOpenUI parameter to the Siebel Tools configuration file:

   1. In Windows Explorer, navigate to the following folder:

      SIEBEL_TOOLS_HOME\bin\language_code
      

      For more information about the language_code, see "Languages That Siebel Open UI Supports".

   2. Use a text editor to open the tools.cfg configuration file.

   3. Add the following parameter to the InfraUIFramework section:

      EnableOpenUI = TRUE
      

2. Display object types:

   1. Open Siebel Tools.

      For more information, see Using Siebel Tools.

   2. Choose the View menu, and then the Options menu item.

   3. Click the Object Explorer tab.

   4. Scroll down through the Object Explorer Hierarchy window to locate the object type you must display.

      It is recommended that you set up Siebel Tools to display all object types. To display an object type and all child object types of an object type, make sure the parent includes a check mark with a white background.

   5. Click OK.

Modifying the Application Configuration File

You can use the configuration file to specify parameters that determine how a specific Siebel application runs. For more information about the application configuration file, see Configuring Siebel Business Applications.

To modify the application configuration file 

1. Open Windows Explorer, and then navigate to the following folder:

   INSTALL_DIR\eappweb\bin\language_code
   

   For more information about the language_code, see "Languages That Siebel Open UI Supports".

2. Use a text editor to open the application configuration file that you must modify.

   Each Siebel application uses a different configuration file. For example, Siebel Call Center uses the uagent.cfg file. The application configuration file uses the .cfg file extension.

3. Locate the section that you must modify.

   Each application configuration file uses square brackets to indicate a section. For example:

   [InfraUIFramework]
   

4. Modify an existing parameter or add a separate line for each parameter that you must specify.

   Use the following format:

   parameter_name = "<param1 param2>"
   

   where:

   • param1 and param2 are the names of the parameters.

   For example:

   TreeNodeCollapseCaption = "<img src='images/tree_collapse.gif' alt='-' border=0 align=left vspace=0 hspace=0>"
   

Deriving Presentation Models, Physical Renderers and Plug-in Wrappers

Deriving is a coding technique that you can use with Siebel Open UI to create a reference between two presentation models, physical renderers, or plug-in wrappers. Where Siebel Open UI derives one presentation model, physical renderer or plug-in wrapper from another presentation model, physical renderer or plug-in wrapper. This referencing can make sure that the derived object uses the same logic as the source object. It also helps to reduce the amount of coding you must perform.

The following code includes all the code required to derive one presentation model from another presentation model:

Note: he same methodology can be applied for physical renderers and plug-in wrappers.

if( typeof( SiebelAppFacade.derived_PM_name) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derived_PM_name" );
  define( "siebel/custom/derived_PM_name", ["siebel/custom/source_PM"],function(){
    . . .
SiebelJS.Extend(derived_PM_name, SiebelAppFacade.source_PM );
});
}

where:

• derived_PM_name is the name of a presentation model that references another presentation model.

• source_PM is the name of a presentation model that provides the code that derived_PM_name uses. The source_PM must already exist.

You must include the define and Extend statements.

For example, the following code derives a presentation model named derivedpm2 from another presentation model, named derivedpm1:

if( typeof( SiebelAppFacade.derivedpm2 ) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derivedpm2" );
  define( "siebel/custom/derivedpm2", ["siebel/custom/derivedpm1"], function(){
    . . .
SiebelJS.Extend( derivedpm2, SiebelAppFacade.derivedpm1 );
});
}

Adding Presentation Model Properties That Siebel Servers Send to Clients

This topic describes how to add presentation model properties that the Siebel Server sends to the client. It includes the following information:

• "Adding Presentation Model Properties That Siebel Servers Send for Applets"

• "Adding Presentation Model Properties That Siebel Servers Send for Views"

• "Customizing Control User Properties for Presentation Models"

It is strongly recommended that you configure custom presentation model properties only if the predefined presentation model properties do not meet your requirements.

Adding Presentation Model Properties That Siebel Servers Send for Applets

This topic describes a general approach to customizing applet user properties for presentation models. The Siebel Server sends these properties to the client.

To add presentation model properties that Siebel Servers send for applets 

1. Add user properties to the applet:

   1. Open Siebel Tools.

      For more information, see Using Siebel Tools.

   2. In the Object Explorer, click Applet.

   3. In the Applets list, query the Name property for the applet that you must modify.

      For example, query the Name property for Contact List Applet.

   4. In the Object Explorer, expand the Applet tree, and then click Applet User Prop.

   5. In the Applet User Props list, add the following applet user property.

      Name

      Value

      ClientPMUserPropn For example, ClientPMUserProp1

      user_property_name You can specify one or more user properties. Siebel Open UI sends these user properties to the presentation model that it uses in the client to display the applet. To specify more than one user property, use a comma and a space to separate each user property name. For example: User Property1, User Property2 Each user property that you specify must exist in the Siebel repository, and each of these user properties must contain a value in the Value property.

      
      

   6. (Optional) Specify more ClientPMUserPropn user properties, as necessary.

      You can specify more than one ClientPMUserPropn user property, as necessary. Repeat Step e for each ClientPMUserPropn user property that you require.

   7. Compile your modifications.

2. Modify the presentation model:

   1. Use a JavaScript editor to open your custom presentation model file that Siebel Open UI will use to display the applet that you modified in Step 1.

   2. If your custom presentation model does not override the Setup method, then configure Siebel Open UI to do this override.

      For more information about how to configure an override, see "Process of Customizing the Presentation Model".

   3. Locate the following section of code:

      presentation_model.Setup(propSet)
      

      For example, if the class name is CustomPM, then locate the following code:

      CustomPM.prototype.Setup = function (propSet)
      

   4. Add the following code to the section that you located in Step c:

      var consts = SiebelJS.Dependency("SiebelApp.Constants");
      var apm = propSet.GetChildByType(consts.get("SWE_APPLET_PM_PS"));
      

      where:

      • SWE_APPLET_PM_PS is a predefined constant that Siebel Open UI uses to get the presentation model properties that it uses to display the applet. The Siebel Server sends these properties in a property set.

   5. Add the following code anywhere in the presentation model:

      var value = apm.GetProperty("user_property_name")
      

      For example:

      var value = apm.GetProperty("User Property1")
      

      You must configure Siebel Open UI so that it runs the Setup method that you specify in Step c before it encounters the code that you add in Step e.

Adding Presentation Model Properties That Siebel Servers Send for Views

This topic describes how to customize view user properties for presentation models. The Siebel Server sends these properties to the client.

To add presentation model properties that Siebel Servers send for views 

1. Add user properties to the view:

   1. Open Siebel Tools.

      For more information, see Using Siebel Tools.

   2. In the Object Explorer, click View.

   3. In the Views list, query the Name property for the view that you must modify.

      For example, query the Name property for Contact List View.

   4. In the Object Explorer, expand the View tree, and then click View User Prop.

   5. Do Step 1e through Step 1g, except add view user properties to a view instead of adding applet user properties to an applet.

2. If your custom view presentation model does not override the Setup method, then configure Siebel Open UI to do this override:

   Do Step 2 except use vpm instead of apm:

   1. Use a JavaScript editor to open the presentation model file that Siebel Open UI uses to display the view that you modified in Step 1.

   2. Add the following code:

      var consts = SiebelJS.Dependency("SiebelApp.Constants");
      var vpm = propSet.GetChildByType(consts.get("SWE_VIEW_PM_PS"));
      

      where:

      • SWE_VIEW_PM_PS is a predefined constant that Siebel Open UI uses to get the presentation model properties that it uses to display the view. The Siebel Server sends these properties in a property set.

   3. Add the following code:

      var value = vpm.GetProperty("user_property_name")
      

      For example:

      var value = vpm.GetProperty("User Property1")
      

   For more information about how to configure an override, see "Process of Customizing the Presentation Model".

Customizing Control User Properties for Presentation Models

This topic describes how to customize control user properties for a presentation model.

To customize control user properties for presentation models 

1. Add user properties to the control:

   1. Open Siebel Tools.

      For more information, see Using Siebel Tools.

   2. In the Object Explorer, click Applet.

   3. In the Applets list, query the Name property for the applet that you must modify.

      For example, query the Name property for Contact List Applet.

   4. In the Object Explorer, expand the Applet tree, and then Control.

   5. In the Controls list, query the Name property for the control that you must modify.

      For example, query the Name property for NewRecord.

   6. In the Object Explorer, expand the Control tree, and then click Control User Prop.

   7. In the Control User Props list, Do Step 1e through Step 1g, except add control user properties to the control instead of adding applet user properties to an applet.

2. Modify the custom presentation model of the applet where the control resides:

   
   

   Note: This step can also be accomplished using a plug-in wrapper written for customizing the control.

   
   

   1. Configure Siebel Open UI to get the control object. You can do one of the following:

      • Use the following code to get the control object from the GetControls presentation model property:

        var controls = this.Get("GetControls");
        for (var control in controls){
        var cpm = control.GetPMPropSet(consts.get("SWE_CTRL_PM_PS"));
        // Do something with cpm
        }
        

      • Use the following the GetControl method to get an instance of the Account Name control:

        var myControl = this.GetControl ("Account Name");
        var cpm = myControl.GetPMPropSet(consts.get("SWE_CTRL_PM_PS"));
        

   2. Add the following code:

      var consts = SiebelJS.Dependency("SiebelApp.Constants");
      var cpm = control.GetPMPropSet(consts.get("SWE_CTRL_PM_PS"));
      

      where:

      • GetPMPropSet is a method that gets the property set for this control. For more information, see "GetPMPropSet Method".

      • SWE_CTRL_PM_PS is a predefined constant that Siebel Open UI uses to get the presentation model that it uses for the control object. The Siebel Server sends these properties in a property set.

   3. Add the following code:

      var value = cpm.GetProperty("user_property_name")
      

      For example:

      var value = cpm.GetProperty("User Property1")
      

Configuring Siebel Open UI to Bind Methods

This topic includes some examples that describe how to bind methods. For other examples that bind methods, see the following topics:

• "Example of the Life Cycle of a User Interface Element"

• "Customizing the Physical Renderer to Refresh the Carousel"

• "Text Copy of Code That Does a Partial Refresh for the Physical Renderer"

Binding Methods That Reside in the Physical Renderer

You can use the AttachPMBinding method to bind a method that resides in a physical renderer and that Siebel Open UI must call when the presentation model finishes processing.

To bind methods that reside in the physical renderer 

1. Add the method reference in the physical renderer.

2. Configure Siebel Open UI to send the scope in the binderConfig argument of the AttachPMBinding method as a scope property.

   For more information, see "AttachPMBinding Method".

Conditionally Binding Methods

The example in this topic conditionally binds a method.

To conditionally bind methods 

• Add the following code:

  this.AttachPMBinding("DoSomething",function(){SiebelJS.Log("After DoSomething");},{when: function(function_name){return false;}});
  

  where:

  • function_name identifies the name of a function.

In this example, if Siebel Open UI calls DoSomething, then the presentation model calls the function_name that the when condition specifies, and then tests the return value. If function_name returns a value of:

• true. Siebel Open UI calls the AttachPMBinding method.

• false. Siebel Open UI does not call the AttachPMBinding method.

If you do not include the when condition, then Siebel Open UI runs the DoSomething method, and then calls the AttachPMBinding method. For more information, see "AttachPMBinding Method".

Calling Methods for Applets and Business Services

This topic includes some examples that describe how to call methods for applets and business services. For other examples that call methods, see the following topics:

• "Customizing the Presentation Model to Delete Records"

• "Attaching an Event Handler to a Presentation Model"

• "Using Custom JavaScript Methods"

• "Using Custom Siebel Business Services"

• "Customizing Siebel Pharma for Siebel Mobile Disconnected Clients"

Calling Methods

The example in this topic describes how to call a method when the user clicks a button.

To call methods for buttons 

1. Modify the plug-in wrapper:

   1. Use a JavaScript editor to open the plug-in wrapper for the button.

   2. Locate the click handler for the button.

   3. Add the following code to the code you located in Step b:

      var inPropSet = CCFMiscUtil_CreatePropSet();
      //Define the inPropSet property set with the information that InvokeMethod sends as input to the method that it calls.
      var ai= {};
      ai.async = true;
      ai.selfbusy = true;
      ai.scope = this;
      ai.mask = true;
      ai.opdecode = true;
      ai.errcb = function(){
        //Code occurs here for the method that Siebel Open UI runs if the AJAX call fails
        };
      ai.cb = function(){
        //Code occurs here for the method that Siebel Open UI runs if the AJAX call is successful
        };
      this.GetPM().ExecuteMethod("InvokeMethod",input arguments, ai);
      

      where:

      • input arguments lists the arguments that InvokeMethod sends as input to the method that it calls.

      For example, the following code specifies to use the InvokeMethod method to call the NewRecord method, using the properties that the inPropSet variable specifies for the ai argument:

      this.GetPM().ExecuteMethod("InvokeMethod", "NewRecord", inPropSet, ai);
      

      For more information, see "InvokeMethod Method for Application Models" and "NewRecord Method".

2. Modify the presentation model:

   1. Use a JavaScript editor to open the presentation model for the applet that you must modify.

   2. Locate the code that calls the Init method.

   3. Add the following code to the code that you located in Step b:

      this.AttachPreProxyExecuteBinding("method_name", function(methodName, inputPS, outputPS){// Include code here that Siebel Open UI runs before the applet proxy sends a reply.});
      
      this.AttachPostProxyExecuteBinding("method_name", function(methodName, inputPS, outputPS){// Include code here that Siebel Open UI runs after the applet proxy sends a reply.});
      

      where:

      • method_name identifies the name of the method that InvokeMethod calls. Note that Siebel Open UI comes predefined to set the value of the methodName argument in the following code to WriteRecord, by default. You must not modify this argument:

        function(methodName, inputPS, outputPS)
        

      For example:

      this.AttachPreProxyExecuteBinding("WriteRecord", function(methodName, inputPS, outputPS){// Include code here that Siebel Open UI runs before the applet proxy sends a reply.});
      
      this.AttachPostProxyExecuteBinding("WriteRecord", function(methodName, inputPS, outputPS){// Include code here that Siebel Open UI runs after the applet proxy sends a reply.});
      

      For more information, see "WriteRecord Method", "AttachPostProxyExecuteBinding Method", and "AttachPreProxyExecuteBinding Method".

Calling Methods for Business Services

The example in this topic describes how to call a method for a business service when the user clicks a button.

To call methods for buttons 

1. Use a JavaScript editor to open the plug-in wrapper for the button.

2. Locate the click handler for the button.

3. Add the following code to the code that you located in Step 2:

   var service = SiebelApp.S_App.GetService("business_service_name");
   if (service) {
     var inPropSet = CCFMiscUtil_CreatePropSet();
     //Code occurs here that sets the inPropSet property set with all information that Siebel Open UI must send as input to the method that it calls.
     var ai = {};
     ai.async = true;
     ai.selfbusy = true;
     ai.scope = this;
     ai.mask = true;
     ai.opdecode = true;
     ai.errcb = function(){
         //Code occurs here for the method that Siebel Open UI runs if the AJAX call fails
       };
     ai.cb = function(){
         //Code occurs here for the method that Siebel Open UI runs if the AJAX call is successful
       };
     service.InvokeMethod("method_name", "input_arguments", ai);
   }
   

   For more information, see "InvokeMethod Method for Presentation Models".

Using the Base Physical Renderer Class With Nonapplet Objects

This topic describes how to use the Base Physical Renderer class with nonapplet objects that you customize. It includes the following topics:

• "Hierarchy That the Base Physical Renderer Class Uses"

• "Modifying Nonapplet Configurations for Siebel CRM Version 8.1.1.10, 8.2.2.3, or Earlier"

• "Declaring the AttachPMBinding Method When Using the Base Physical Renderer Class"

• "Sending an Arbitrary Scope"

• "Accessing Proxy Objects"

The BasePhysicalRenderer class simplifies calls that Siebel Open UI makes to the AttachPMBinding method for nonapplet objects. You can configure Siebel Open UI to use the BasePhysicalRenderer class to identify the physical renderer, call AttachPMBinding, and specify the configuration for the scope of a nonapplet object. You can then use a custom physical renderer to call AttachPMBinding with the appropriate handler.

Siebel Open UI uses the PhysicalRenderer class to interface with and to render applets. Starting with Siebel CRM versions 8.1.1.11 and 8.2.2.4, it uses the BasePhysicalRenderer class to render nonapplet objects. It uses this class to separate the interface to the physical renderer from the physical renderer. Siebel Open UI uses the BasePhysicalRenderer class only with nonapplet objects, such as the toolbar or predefined query bar.

If your deployment includes nonapplet custom rendering, and if it uses Siebel CRM version 8.1.1.10, 8.2.2.3 or earlier, then it is strongly recommended, but not required, that you modify your configuration so that it uses the BasePhysicalRenderer class to render your custom, nonapplet objects. If your deployment uses the PhysicalRenderer class to render nonapplet objects, then this class will provide access to applet functionality and properties that it does not require to do the rendering, which could degrade performance or result in rendering problems.

Siebel Open UI defines the BasePhysicalRenderer class in the basephyrenderer.js file.

Hierarchy That the Base Physical Renderer Class Uses

Figure 5-1 illustrates the hierarchy that the BasePhysicalRenderer class uses for non-mobile applications. The member variable is a variable that is associated with the class. All methods can access this member variable.

Figure 5-1 Hierarchy That the Base Physical Renderer Class Uses

Using Methods with the Base Physical Renderer Class

Table 5-2 describes how to use methods with the BasePhysicalRenderer class.

Table 5-2 How to Use Methods with the Base Physical Renderer Class

Method	Description
Init	Use this method to initialize the BasePhysicalRenderer class. For more information, see "Init Method".
GetPM	Use this method to retrieve the presentation model object on which the base physical renderer is running. For more information, see "GetPM Method for Physical Renderers".
ShowUI	Use this method to display the DOM area corresponding to this physical renderer. Any customization on rendering of controls owned by this applet should be left to the respective plug-in wrappers. For more information, see "ShowUI Method" and "Deriving Presentation Models, Physical Renderers and Plug-in Wrappers".
BindEvents	Use this method to attach event handlers to the applet area that runs on this physical renderer. Any customizations relating to event attachment to controls owned by this applet should be left to the respective plug-in wrappers. For more information, see "BindEvents Method".
BindData	Use this method to bind data attributes to the applet area that runs on this physical renderer. Any customizations relating to event attachment to controls owned by this applet should be left to the respective plug-in wrappers. For more information, see "BindData Method" and "Deriving Presentation Models, Physical Renderers and Plug-in Wrappers".
AttachPMBinding	Use this method to configure Siebel Open UI to do the same work that the AttachPMBinding method does in a presentation model. You can use the following argument to call the AttachPMBinding method: scope You can use the following arguments with the AttachPMBinding method: methodName. Identifies the method that the BasePhysicalRenderer class binds. handler. Identifies the handler method that Siebel Open UI uses for this binding. handlerScope. Identifies the scope where the BasePhysicalRenderer class runs the handler. If you do not specify the handlerScope, then the BasePhysicalRenderer class uses the default scope. For more information, see "AttachPMBinding Method".
EndLife	Use this method to end the life of the physical renderer. It is recommended that you use the EndLife method to clean up the custom event handler. This clean up includes releasing events, deleting unused variables, and so on. For more information, see "EndLife Method".

Declaring the AttachPMBinding Method When Using the Base Physical Renderer Class

If you configure Siebel Open UI to use the BasePhysicalRenderer class, then you must declare the AttachPMBinding method.

To declare the AttachPMBinding method when using the Base Physical Renderer class 

1. Use a JavaScript editor to open your custom physical renderer.

2. Locate the Init method.

3. Add the following code to the Init method that you located in Step 2:

   CustomPhysicalRenderer.prototype.Init = function(){
     // Be a good citizen. Call Superclass first
     SiebelAppFacade.CustomPhysicalRenderer.superclass.Init.call(this);
     // Call AttachPMBinding here.
   }
   

   For example:

   CustomPhysicalRenderer.prototype.Init = function(){
     SiebelAppFacade.CustomPhysicalRenderer.superclass.Init.call(this);
     this.AttachPMBinding("EndQueryState", EndQueryState);
   }
   

Sending an Arbitrary Scope

An arbitrary scope is any scope other than the scope that calls the handler. You can configure Siebel Open UI to send to the AttachPMBinding method any scope that is available in the physical renderer. You can use the BasePhysicalRenderer class to send an arbitrary scope that identifies the handler method that Siebel Open UI must use.

To send an arbitrary scope 

1. Use a JavaScript editor to open your custom physical renderer.

2. Add the following code to send an arbitrary scope as an argument:

   this.AttachPMBinding ("FocusOnApplet", FocusOnApplet, arbitrary_scope );
   

   For example:

   this.AttachPMBinding ("FocusOnApplet", FocusOnApplet, SiebelAppFacade.S_App);
   

   where:

   • SiebelAppFacade.S_App is an arbitrary scope because it is not the calling scope that the this statement identifies, which Siebel Open UI assumes in BasePR, by default. In this example, the FocusOnApplet handler must exist in the SiebelAppFacade.S_App scope.

Accessing Proxy Objects

If you must write code that accesses a proxy object, then it is strongly recommended that you access this proxy object through a physical renderer. The physical renderer typically exposes the interfaces that allow access to operations that Siebel Open UI performs on the proxy object. The example in this topic accesses a proxy object for an active control.

To access proxy objects 

1. Use a JavaScript editor to open your custom physical renderer.

2. Add the following code:

   this.ExecuteMethod("SetActiveControl", control);
   

   This example code accesses a proxy object so that Siebel Open UI can modify an active control.

It is recommended that you do not write code that directly accesses a proxy object from a physical renderer. In the following example, Siebel Open UI might remove the GetProxy method from the presentation model, and any code that references GetProxy might fail. It is recommended that you do not use the following code:

this.GetProxy().SetActiveControl(control);

Modifying Nonapplet Configurations for Siebel CRM Version 8.1.1.10, 8.2.2.3, or Earlier

Siebel Open UI removed the scope argument for calls that it makes to the AttachPMBinding method with nonapplet objects, starting with Siebel CRM versions 8.1.1.11 and 8.2.2.4. You can modify your custom code to use this new configuration.

To modify nonapplet configurations for Siebel CRM versions 8.1.1.10, 8.2.2.3, or earlier 

1. Use a JavaScript editor to open your custom physical renderer.

2. Locate the following code:

   this.GetPM().AttachPMBinding ("FocusOnApplet", FocusOnApplet, {scope:this});
   

   In this example, AttachPMBindings uses the scope argument to do a call in Siebel CRM version 8.1.1.10, 8.2.2.3, or earlier.

3. Replace the code that you located in Step 2 with the following code:

   this.AttachPMBinding ("FocusOnApplet", FocusOnApplet);
   

   You can use this code starting with Siebel CRM versions 8.1.1.11 and 8.2.2.4.

Creating Components

The example in this topic configures Siebel Open UI to attach a local component

as the child of a view component, and it uses the property set that Siebel Open UI uses to create this component to specify the name of the module.

Siebel Open UI uses this module for the presentation model and the physical renderer.

To create components 

1. Create the property set. Use the following code:

   var psInfo = CCFMiscUtil_CreatePropSet();
   psInfo.SetProperty(consts.get("SWE_UIDEF_PM_CTR"), "siebel/custom/customPM");
   psInfo.SetProperty(consts.get("SWE_UIDEF_PR_CTR"), "siebel/custom/customPR");
   

   where:

   • siebel/custom/customPM is the module name that identifies the siebel/custom/customPM.js presentation model

   • siebel/custom/customPR is the module name that identifies the siebel/custom/customPR.js physical renderer

2. Create the dependency object. Use the following code:

   var dependency = {};
   dependency.GetName = function(){return "custom_Dependency_object";}
   

   This example assumes that it is not necessary that this component references an applet, so the code limits the scope to a view.

3. Call the MakeComponent method. Use the following code:

   SiebelAppFacade.ComponentMgr.MakeComponent(SiebelApp.S_App.GetActiveView(), psInfo, dependency);
   

   For more information, see "MakeComponent Method" and "GetActiveView Method".

Allowing Users to Interact with Clients During Business Service Calls

The user cannot interact with the client during a synchronous request to a business service until the client receives the reply for this request from the Siebel Server. However, the user can interact with the client while it is waiting for a reply during an asynchronous request. This topic describes how to write JavaScript code so that it sends an asynchronous request that allows the user to continue to use the client without interruption during the call. You use the following code to specify an asynchronous call:

async = true or false

For example, the following code makes an asynchronous request:

async = true

To view an example presentation model that includes more than one instance of enabling and disabling an asynchronous call, download the msgbrdcstpmsync.js file, and then search this file for the following string:

lpsca.async

To get a copy of this file, see Article ID 1494998.1 on My Oracle Support.

For more information, see "About Synchronous and Asynchronous Requests".

To allow users to interact with clients during business service calls 

1. Use a JavaScript editor to open the presentation model that you must modify.

2. Locate the ExecuteMethod that calls the business service that you must modify.

   Siebel Open UI uses the ExecuteMethod method to call a business service. For more information, see "ExecuteMethod Method".

3. Add the following code to the ExecuteMethod call that you located in Step 2:

   var service = SiebelApp.S_App.GetService("service_name");
   var inPropSet = SiebelApp.S_App.NewPropertySet ();
   // set all the input arguments through inPropSet.SetProperty("property_name",
   "property_value")
   var outPropSet;
   if(service){
     var config = {};
     config.async = true;
     config.scope = this;
     config.cb = function(){
       outPropSet = arguments[2];
       if (outPropSet!== null){
         output_property_set
       }
     }
     service.InvokeMethod ("method_name", inPropSet, config);
   }
   

   where:

   • inPropSet.SetProperty allows you to add input arguments to the business service that resides on the Siebel Server.

   • service_name is the name of the business service that Siebel Open UI must call.

   • config.async is set to true.

   • config.scope = this attaches a scope to the callback function so that you are not required to use var that=this to resolve the scope. For more information, see "Coding Callback Methods".

   • method_name is the name of a business service method that resides in the business service that you specify in service_name.

   • output_property_set is the name of the property set that Siebel Open UI uses to store the output of this asynchronous call.

   For example, the following code creates an asynchronous call to create a list of quotes:

   var service = SiebelApp.S_App.GetService("Create Quote Service");
   var inPropSet = SiebelApp.S_App.NewPropertySet ();
   var outPropSet;
   if(service){
     var config = {};
     config.async = true;
     config.scope = this;
     config.cb = function(){
       outPropSet = arguments[2];
       if (outPropSet!== null){
         quoteList
       }
   
     service.InvokeMethod ("Create Quote", inPropSet, config);
   }
   

   where:

   • quoteList is an output property set that contains a list of quotes that Siebel Open UI gets from the Create Quote business service method.

Customizing How Siebel Open UI Displays Error Messages

Prior to Siebel CRM release 8.1.1.13, Siebel Open UI used the ErrorObject method to display the error dialog box. This method calls a browser alert method that displays the dialog box as a browser notification. Beginning with Siebel CRM release 8.1.1.13, you can modify this configuration so that Siebel Open UI displays the notification in a status bar or in a custom dialog box.

Siebel Open UI uses the following rendering files to display error messages:

• errorobjectrenderer.js. Displays an error alert or SWEAlert message.

• errorstatusbarrenderer.js. Displays an error message in a custom error status bar in the browser.

• errorpopuprenderer.js. Displays a custom dialog box that includes an error message.

Note the following:

• The errorobjectrenderer.js file is the only file that comes predefined with Siebel Open UI and does not require you to configure the manifest or to modify a method. You must not modify this file.

• The manifest does not come predefined to use the errorstatusbarrenderer.js file or the errorpopuprenderer.js file. If your customization requires one of these files, then you must add it to the manifest.

• Siebel Open UI renders only one of these files at a time. If you add errorstatusbarrenderer.js or errorpopuprenderer.js to the manifest, then Siebel Open UI uses one of these files instead of errorobjectrenderer.js.

• These files use the following constructor. You must not modify this constructor:

  SiebelApp.S_App.ErrorObjectRenderer
  

• These files reference the following method. For more information about this method, see "ShowErrorMessage Method":

  ShowErrorMessage(message)
  

• Each file uses the typical sequence that a physical renderer uses. For example, each file calls the following methods in the following sequence. You must not modify this sequence. For more information, see "Life Cycle of a Physical Renderer":

  1. ShowUI

  2. BindData

  3. BindEvents

For more information about configuring error messages in Siebel Open UI, see "Configuring Error Messages for Disconnected Clients".

To customize how Siebel Open UI displays error messages 

1. Optional. Modify the style that Siebel Open UI uses when it displays the error status bar.

   If your customization uses the errorstatusbarrenderer.js file, then you can style the status bar by adding style rules for the siebui-statusbar class in a custom cascading style sheet and place it in following folder:

   files\custom\my-style.css
   

   You must add the style sheet to the manifest by following the steps outlined in "Configuring Manifests".

2. Configure the manifest. For more information about how to do this step, see "Configuring Manifests":

   1. Log in to a Siebel client with administrative privileges.

   2. Navigate to the Administration - Application screen, and then the Manifest Files view.

   3. Add one of the following files, depending on your customization requirements:

      custom/errorstatusbarrenderer.js
      custom/errorpopuprenderer.js
      

   4. Navigate to the Manifest Administration view.

   5. In the UI Objects list, specify the following object.

      Field	Value
      Type	Application
      Usage Type	Theme
      Name	PLATFORM INDEPENDENT

      
      

   6. In the Object Expression list, add the following subexpression.

      Field	Value
      Group Name	Leave empty.
      Expression	Desktop
      Level	1 Siebel Open UI only uses the renderer whose level is set to 1.
      Operator	Leave empty.
      Web Template Name	Leave empty.

      
      

   7. In the Files list, click Add.

   8. In the Files dialog box, click Query.

   9. In the Name field, enter the path and file name that you added in Step c:

      files/custom/my-style.css
      

   10. Click Go.

3. Test your work:

   1. Log out of, and then log back into the client.

   2. Do something that results in an error.

   3. Verify that the client displays an error message according to your modifications.

Customizing Navigation Options

The Siebel Open UI client can be configured to control the navigation options available to users. By default the Side Menu icon is used to control navigation. Without configuration, two additional options are available for navigation: Tab and Tree.

In some deployments, you might want to restrict the use of a navigation option to a predefined group. This topic explains how to control which navigation options are available to which users.

To customize the available navigation options 

1. Create an expression for the navigation option that you want to restrict:

   1. Log in to a Siebel client with administrative privileges.

   2. Navigate to the Administration - Application screen, and then the Manifest Expressions view.

   3. Click the plus (+) icon to create a new expression.

   4. Specify a name for the expression.

   5. Specify the restrictive expression.

2. Create a copy of the navigation type that you want to restrict:

   1. Navigate to the Administration - Application screen, and then the Manifest Administration view.

   2. In the UI Objects list, search with the following specifications:

      Field	Value
      Type	Navigation
      Usage Type	Physical Renderer
      Name	NAVIGATION* You can reference any navigation option.

      
      

   3. Select the navigation option that you want to modify. The three available options are NAVIGATION_SIDE, NAVIGATION_TAB, and NAVIGATION_TREE.

   4. Take note of the exact file name that is listed in Files applet, you will need this information in a later step.

   5. Select the Edit menu, then Copy Record.

3. Edit the navigation type:

   1. Select the copy of the navigation type that you created in Step 2.

   2. Click the plus (+) icon in Object Expression applet.

   3. In the Expression field, specify the expression that you created in Step 1.

   4. Click the plus (+) icon in the Files applet and add the file that you noted in Step 2d.

4. Verify your work:

   1. Log out of the client, and then log back into the client.

      This step refreshes the manifest.

   2. Navigate to the User Preferences screen, then the Behavior view.

   3. Verify that the correct options are available in the Navigation Control drop-down menu for the user with which you are logged in.

Example of Restricting Navigation Options

The example in this topic describes how to restricts the Tree navigation option to only the ADMIN user in Siebel Open UI.

This topic gives one example of restricting navigation options. You might use this feature differently, depending on your business model.

To restrict the Tree navigation option to only the ADMIN user 

1. Create an expression that restricts availability to administrator only:

   1. Log in to a Siebel client with administrative privileges.

   2. Navigate to the Administration - Application screen, and then the Manifest Expressions view.

   3. Click the plus (+) icon create a new expression.

   4. Specify the following in the Name field:

      Admin Only

   5. Specify the following in the Expression field:

      GetProfileAttr('Login Name') = 'ADMIN'
      

2. Create a copy of the NAVIGATION_TREE object:

   1. Navigate to the Administration - Application screen, and then the Manifest Administration view.

   2. In the UI Objects list, search with the following specifications:

      Field	Value
      Type	Navigation
      Usage Type	Physical Renderer
      Name	NAVIGATION_TREE

      
      

   3. Select the NAVIGATION_TREE record.

   4. Select the Edit menu, then Copy Record.

3. Edit the new NAVIGATION_TREE record:

   1. Select the copy of the NAVIGATION _TREE record.

   2. Click the plus (+) icon in Object Expression applet.

   3. In the Expression field, specify the expression Admin Only.

   4. Click the plus (+) icon in the Files applet to add the following file:

      jsTreeCtrl.js

4. Verify your work:

   1. Log out of the client, and then log back into the client as a user other than ADMIN.

   2. Navigate to the User Preferences screen, then the Behavior view.

   3. Verify that the only the following two options are available in the Navigation Control drop-down menu:

      • Side Menu

      • Tab

   4. Log out of the client, and then log back into the client as the ADMIN user.

   5. Navigate to the User Preferences screen, then the Behavior view.

   6. Verify that the only the following three options are available in the Navigation Control drop-down menu:

      • Side Menu

      • Tab

      • Tree