Customizing Events

This topic includes some examples that describe how to customize the way Siebel Open UI uses events. It includes the following information:

"Refreshing Custom Events"
"Overriding Event Handlers"
"Attaching an Event Handler to an Event"
"Attaching More Than One Event Handler to an Event"
"Stopping Siebel Open UI From Calling Event Handlers"
"Attaching and Validating Event Handlers in Any Sequence"
"Customizing the Sequence that Attaches and Validates Event Handlers"
"Using AttachEventHandler Prior to Siebel CRM Release 8.1.1.13"
"Overriding the OnControlEvent Method and Then Calling a Superclass"
"Allowing Blocked Methods for HTTP GET Access"

For more information about how Siebel Open UI uses events and examples that configure them, see the following topics:

Refreshing Custom Events

Siebel Open UI does not come predefined to refresh a custom event. The example in this topic describes how to modify this behavior.

To refresh custom events

Add the following code:

this.AddMethod("RefreshHandler", function(x, y, z){
  // Add code here that does processing for RefreshHandler.
});

This code adds the RefreshHandler custom event handler.

Add the following code in the presentation model so that it is aware of the event that the RefreshEventHandler specifies:
```
this.AttachEventHandler("Refresh", "RefreshHandler");
```
For more information, see "AttachEventHandler Method".
Add the following code in the bindevents method of the plug-in wrapper:
```
this.Helper("EventHelper").Manage(buttonEl, "click", { ctx: this }, function(event){
      event.data.ctx.GetPM().OnControlEvent("Refresh", value1, value2, valueN);
```
This code binds the event to the presentation model. For more information, see "OnControlEvent Method".

Overriding Event Handlers

The example in this topic configures Siebel Open UI to override an event handler that the predefined presentation model references.

To override event handlers

Configure Siebel Open UI to refresh a custom event.

For more information, see "Customizing Events".
Add the following code to your custom presentation model:
```
this.AddMethod(SiebelApp.Constants.get("PHYEVENT_INVOKE_CONTROL"), function(controlName) {
  // Process button click
  return false;
});
```
This code configures Siebel Open UI to return the following value from the event handler. It makes sure this presentation model does not continue processing:
```
false
```

Attaching an Event Handler to an Event

This topic describes how to attach an event handler to an event.

To attach an event handler to an event

Use the following code:

this.AddMethod("custom_method", function(){});
this.AttachEventHandler("custom_event", "custom_method");

The physical renderer or the plug-in wrapper triggers these handlers when the following code is executed:

this.GetPM().OnControlEvent("custom_event", param1, param2)

The presentation model uses the custom_method to identify the function that it must call and when to call it. The presentation model also sends the parameters that OnControlEvent provides. For more information, see "AttachEventHandler Method".

Attaching More Than One Event Handler to an Event

This topic describes how to attach more than one event handler to an event.

To attach more than one event handler to an event

Use the following code:

this.AttachEventHandler("custom_event", "custom_method_1");
this.AttachEventHandler("custom_event", "custom_method_2");
this.AttachEventHandler("custom_event", "custom_method_3");

The physical renderer or the plug-in wrapper triggers these handlers when the following code is executed:

this.GetPM().OnControlEvent( "custom_event",  param1, param2)

The presentation model determines that it must handle three events, and it handles them in the reverse order that you specify them. In this example, it uses the following sequence when it handles the event:

custom_method_3
custom_method_2
custom_method_1

The presentation model sends the same values for the parameters that OnControlEvent specifies for each event handler.

For more information, see "AttachEventHandler Method".

Stopping Siebel Open UI From Calling Event Handlers

You can configure the AttachEventHandler method to stop calling event handlers at any point during the event handling process. The example in this topic assumes your configuration includes one predefined event handler and three custom event handlers, and that custom_event_handler_2 stops the processing according to a condition.

To stop Siebel Open UI from calling event handlers

Use the following code:

this.AddMethod("custom_event_handler_2", function(param1, param2, returnStructure){
  if(condition){
    returnStructure[consts.get("SWE_EXTN_CANCEL_ORIG_OP") ] = true;
    returnStructure[consts.get("SWE_EXTN_STOP_PROP_OP") ] = true;
    returnStructure[consts.get("SWE_EXTN_RETVAL") ] = return_value ;
  }
});
this.AttachEventHandler("event_name", "custom_event_handler_2");

where:

consts references SiebelApp.Constants.
return_value contains a value that Siebel Open UI returns to the object that called OnControlEvent.

This code does the following work:

Sets the SWE_EXTN_CANCEL_ORIG_OP and SWE_EXTN_STOP_PROP_OP properties according to a condition.
Stops event handlers from running.
Uses SWE_EXTN_RETVAL to return a value to the object that called OnControlEvent.

For more information, see "AttachEventHandler Method".

Attaching and Validating Event Handlers in Any Sequence

You can configure Siebel Open UI to attach and validate an event handler in any sequence, depending on your requirements. The example in this topic does some custom validation, and then runs an event handler in a custom presentation model named derivedpm2.js. If the user triggers a control focus event, then Siebel Open UI runs the validator before it calls the event. Siebel Open UI uses the the value that the validator returns to determine whether or not to run the custom event handler and the predefined event handler. This predefined event handler is the default event handler that the predefined presentation model uses for the event. This topic describes the derivedpm1.js and derivedpm2.js files. To get a copy of these files, see Article ID 1494998.1 on My Oracle Support.

To attach and validate event handlers in any sequence

Use a JavaScript editor to create a custom presentation model that Siebel Open UI derives from a predefined presentation model:

Create a new file named derivedpm1.js. Save this file in the following folder:
```
siebel\custom
```
For more information about:
- This file, see "Complete Contents of the derivedpm1 Presentation Model".
- This folder, see "Organizing Files That You Customize".

Configure the custom derivedpm1 presentation model that you created in Step a so that Siebel Open UI derives it from the predefined ListPresentationModel. You add the following code:

if( typeof( SiebelAppFacade.derivedpm1 ) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derivedpm1" );
  define( "siebel/custom/derivedpm1", [], function(){
    SiebelAppFacade.derivedpm1 = ( function(){
      var siebConsts = SiebelJS.Dependency( "SiebelApp.Constants" ),
        CANCEL_OPR = consts.get( "SWE_EXTN_CANCEL_ORIG_OP" ),
        STOP_PROP = consts.get( "SWE_EXTN_STOP_PROP_OP" );
      function derivedpm1(){
        SiebelAppFacade.derivedpm1.superclass.constructor.apply( this, arguments     );
      }
      SiebelJS.Extend( derivedpm1, SiebelAppFacade.ListPresentationModel );
      derivedpm1.prototype.Init = function(){
        SiebelAppFacade.derivedpm1.superclass.Init.call( this );

For more information, see "Deriving Presentation Models, Physical Renderers and Plug-in Wrappers".

Make sure the derivedpm1 presentation model includes a handler for the PHYEVENT_COLUMN_FOCUS event. You add the following code:

        this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
        {
          SiebelJS.Log("Control focus 1");
          arguments[arguments.length - 1][consts.get( "SWE_EXTN_CANCEL_ORIG_OP" )] = false;
        });

For more information about the method that this code uses, see "AttachEventHandler Method".

Validate the handler that you added in c. You add the following code:
```
  this.AddValidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(){
    return true;
  });
};
```
For more information about the method that this code uses, see "AddValidator Method".

Finish the setup that you started in b. You add the following code:

      derivedpm1.prototype.Setup = function(propSet){
        SiebelAppFacade.derivedpm1.superclass.Setup.call( this, propSet );
      };
      return derivedpm1;
    } ());
    return "SiebelAppFacade.derivedpm1";
  });
}

Save your changes, and then close the derivedpm1.js file.

Use a JavaScript editor to create another custom presentation model that Siebel Open UI derives from the custom presentation model that you created in Step 1:

Create a new file named derivedpm2.js. Save this file in the following folder:
```
siebel\custom
```
For more information about this file, see "Complete Contents of the derivedpm2 Presentation Model".

Configure the custom derivedpm2 presentation model that you created in Step a so that Siebel Open UI derives it from the derivedpm1 presentation model. You add the following code:

if( typeof( SiebelAppFacade.derivedpm2 ) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derivedpm2" );
  define( "siebel/custom/derivedpm2", ["siebel/custom/derivedpm1"], function(){
    SiebelAppFacade.derivedpm2 = ( function(){
      var siebConsts = SiebelJS.Dependency( "SiebelApp.Constants" ),
        CANCEL_OPR = consts.get( "SWE_EXTN_CANCEL_ORIG_OP" ),
        STOP_PROP = consts.get( "SWE_EXTN_STOP_PROP_OP" );
      function derivedpm2(){
        SiebelAppFacade.derivedpm2.superclass.constructor.apply( this, arguments );
      }
      SiebelJS.Extend( derivedpm2, SiebelAppFacade.derivedpm1 );
      derivedpm2.prototype.Init = function(){
        SiebelAppFacade.derivedpm2.superclass.Init.call( this );

Make sure the derivedpm2 presentation model includes a handler for the PHYEVENT_COLUMN_FOCUS event. You add the following code:
```
this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
{
  SiebelJS.Log("Control focus 2");
});
```

Validate the handler that you added in Step c. You add the following code:

this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
{
  SiebelJS.Log("Control focus 2");
});
this.AddValidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(row, ctrl, val){
  //custom validation
  }
});

where:

custom validation validates the values.

For example, the following code validates that the handler handles the Hibbing Mfg account:

this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
{
  SiebelJS.Log("Control focus 2");
});
this.AddValidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(row, ctrl, val){
  if(ctrl.GetDisplayName() === "Account" && val === "Hibbing Mfg"){
    return true;
  }
});

Finish the setup that you started in Step b. You add the following code:

      };
      derivedpm2.prototype.Setup = function(propSet){
        SiebelAppFacade.derivedpm2.superclass.Setup.call( this, propSet );
      };
      return derivedpm2;
    } ());
    return "SiebelAppFacade.derivedpm2";
  });
}

Save your changes, and then close the derivedpm2.js file.

Configure the manifest. For more information about how to do this step, see "Adding Custom Manifest Expressions":
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 the file that you created in Step 2.
  
  For this example, you add the following file:
```
custom/derivedpm2.js
```
  Note that your configuration derives the derivedpm2.js from the derivedpm1.js file, so it is not necessary to add derivedpm1.js to the manifest.
4. Navigate to the Manifest Administration view.
5. In the UI Objects list, specify the following object.
  
  Field Value
  
  Type Applet
  
  Usage Type Presentation Model
  
  Name Opportunity List Applet
  You can reference any list applet. For this example, use Opportunity List Applet.
6. In the Object Expression list, add the following subexpression.
  
  Field Value
  
  Group Name Leave empty.
  
  Expression Desktop
  
  Level 1
  
  Operator Leave empty.
  
  Web Template Name Leave empty.
7. In the Files list, add the following file:
```
custom/derivedpm2.js
```
8. Log out of the client, and then log back into the client.
  
  This step refreshes the manifest.
Verify your work:
1. Navigate to the Opportunity List Applet.
2. Click anywhere in the Account field.
3. Verify that the browser console log displays the following text:
```
Control Focus 2
```
  The handler that you specified in the derivedpm2.js file in Step 2 specifies this text.
4. Verify that the browser console log displays the following text:
```
Control Focus 1
```
  The handler that you specified in the derivedpm1.js file in Step 1 specifies this text.

Field	Value
Type	Applet
Usage Type	Presentation Model
Name	Opportunity List Applet You can reference any list applet. For this example, use Opportunity List Applet.

Field	Value
Group Name	Leave empty.
Expression	Desktop
Level	1
Operator	Leave empty.
Web Template Name	Leave empty.

Complete Contents of the derivedpm1 Presentation Model

The following code is the complete contents of the derivedpm1 presentation model:

if( typeof( SiebelAppFacade.derivedpm1 ) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derivedpm1" );
  define( "siebel/custom/derivedpm1", [], function(){
    SiebelAppFacade.derivedpm1 = ( function(){
      var siebConsts = SiebelJS.Dependency( "SiebelApp.Constants" ),
        CANCEL_OPR = consts.get( "SWE_EXTN_CANCEL_ORIG_OP" ),
        STOP_PROP = consts.get( "SWE_EXTN_STOP_PROP_OP" );
      function derivedpm1(){
        SiebelAppFacade.derivedpm1.superclass.constructor.apply( this, arguments     );
      }
      SiebelJS.Extend( derivedpm1, SiebelAppFacade.ListPresentationModel );
      derivedpm1.prototype.Init = function(){
        SiebelAppFacade.derivedpm1.superclass.Init.call( this );
        this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
        {
          SiebelJS.Log("Control focus 1");
          arguments[arguments.length - 1][consts.get( "SWE_EXTN_CANCEL_ORIG_OP" )] = false;
        });
        this.AddValidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(){
          return true;
        });
      };
      derivedpm1.prototype.Setup = function(propSet){
        SiebelAppFacade.derivedpm1.superclass.Setup.call( this, propSet );
      };
      return derivedpm1;
    } ());
    return "SiebelAppFacade.derivedpm1";
  });
}

Complete Contents of the derivedpm2 Presentation Model

The following code is the complete contents of the derivedpm2 presentation model:

if( typeof( SiebelAppFacade.derivedpm2 ) === "undefined" ){
  SiebelJS.Namespace( "SiebelAppFacade.derivedpm2" );
  define( "siebel/custom/derivedpm2", ["siebel/custom/derivedpm1"], function(){
    SiebelAppFacade.derivedpm2 = ( function(){
      var siebConsts = SiebelJS.Dependency( "SiebelApp.Constants" ),
        CANCEL_OPR = consts.get( "SWE_EXTN_CANCEL_ORIG_OP" ),
        STOP_PROP = consts.get( "SWE_EXTN_STOP_PROP_OP" );
      function derivedpm2(){
        SiebelAppFacade.derivedpm2.superclass.constructor.apply( this, arguments );
}
SiebelJS.Extend( derivedpm2, SiebelAppFacade.derivedpm1 );
derivedpm2.prototype.Init = function(){
SiebelAppFacade.derivedpm2.superclass.Init.call( this );
this.AttachEventHandler( siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
{
SiebelJS.Log("Control focus 2");
});
this.AddValidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(row, ctrl, val){
if(ctrl.GetDisplayName() === "Account" && val === "Hibbing Mfg"){
return true;
}
});
};
derivedpm2.prototype.Setup = function(propSet){
SiebelAppFacade.derivedpm2.superclass.Setup.call( this, propSet );
};
return derivedpm2;
} ());
return "SiebelAppFacade.derivedpm2";
});
}

Customizing the Sequence that Attaches and Validates Event Handlers

The example in this topic illustrates how you can modify the sequence that Siebel Open UI uses to attach and validate event handlers so that it stops any further event handler processing after a validation occurs. It does some custom validation, and then runs an event handler in a file named derivedpm2.js. If the user triggers a control focus event, then Siebel Open UI runs the custom event handler that displays a message in the Browser console log. The validator then returns a value of false, so Siebel Open UI stops any further event handler processing for the custom event handler and for the predefined event handler.

To customize the sequence that attaches and validates event handlers

Do Step 1.

Do Step 2 , but specify the validator first, and then the event handler. You use the following code:

this.Addvalidator(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function(){
  custom validation
  return true;
});
this.AttachEventHandler(siebConsts.get("PHYEVENT_COLUMN_FOCUS"), function()
{
  Siebjs.Log("Control Focus 2");
});

For more information about the methods that this code uses, see "AddValidator Method" and "AttachEventHandler Method".

Do Step 4 , but verify that Siebel Open UI displays the following text in the browser console log:
```
Control Focus 2
Control Focus 1
```

Using AttachEventHandler Prior to Siebel CRM Release 8.1.1.13

Prior to Siebel CRM release 8.1.1.13, the AttachEventHandler method returns one of the following values. This configuration allows AttachEventHandler to attach only one custom event to an event:

true. Attached an event handler successfully.
false. Did not attach an event handler successfully.

It uses the following syntax:

AttachEventHandler("eventName", eventHandler());

where:

eventName is a string that identifies the name of the event that Siebel Open UI must attach to the event.
eventHandler identifies the method that Siebel Open UI calls.

For more information, see "AttachEventHandler Method".

Overriding the OnControlEvent Method and Then Calling a Superclass

You must not configure Siebel Open UI to override the OnControlEvent method to handle an event, and then call a superclass. For example, assume you configure Siebel Open UI to override the listpmodel.js file, and that the derived class resides in the derivedpm1.js file. Assume you then use the following code to override the OnControlEvent method that resides in the pmodel.js file. This file specifies the base presentation model class:

derivedpm1.prototype.OnControlEvent = function(event_name)
{
}

In this situation, when an event occurs, Siebel Open UI calls the overridden OnControlEvent instead of the pmodel.prototype.OnControlEvent. You must avoid this configuration. For more information, see "OnControlEvent Method".

Allowing Blocked Methods for HTTP GET Access

In Siebel Innovation Pack 2014 and later, read and write operations have been separated for all applets, business components, and business service methods.

If you want to allow access to a blocked method for HTTP GET access, a user property has been introduced for applets and business services to include methods on a white list, thereby allowing access using HTTP GET.

This topic describes how to allow blocked methods for HTTP GET access using the GETEnabledMethods user property.

To allow blocked methods for HTTP GET access

Open Siebel Tools.

For more information, see Using Siebel Tools.
In the Object Explorer, click Applet.
In the Applets list, locate the applet or business service to which you want to add the GETEnabledMethods user property.
In the Object Explorer, expand the Applet tree, and then click Applet User Prop.
In the Applet User Props list, add the user property with the values:

Field Value

Name GETEnabledMethods

Value MethodName1, MethodName2, ... MethodNameN
Where MethodNameX is the name of a method that should be accessible by way of HTTP GET.

Field	Value
Name	GETEnabledMethods
Value	MethodName1, MethodName2, ... MethodNameN Where MethodNameX is the name of a method that should be accessible by way of HTTP GET.

Note:

It is recommended to list only read-only methods in the white list for HTTP GET access. Methods that perform write operations should not be listed.