Configuring Siebel Open UI > Application Programming Interface > Methods of the Siebel Open UI Application Programming Interface >

Presentation Model Class

This describes the methods that Siebel Open UI uses with the PresentationModel class. It includes the following information:

• AddComponentCommunication Method
• AddLocalString Method
• AddMethod Method
• AddProperty Method
• AddValidator Method
• AttachEventHandler Method
• AttachNotificationHandler Method
• AttachPMBinding Method
• AttachPostProxyExecuteBinding Method
• AttachPreProxyExecuteBinding Method
• ExecuteMethod Method
• Get Method
• GetCtrlTemplate Method
• Init Method
• OnControlEvent Method
• SetProperty Method
• Setup Method for Presentation Models

Siebel Open UI defines the PresentationModel class in the pmodel.js file.

The AddComponentCommunication method binds a communication method. It uses the following arguments:

• methodName is a string that identifies the communication method that Siebel Open UI binds.
• targetMethod is a string that identifies the method that Siebel Open UI calls after methodName finishes. It calls this target method in the presentation model context.
• targetMethodConfig identifies an object that contains configuration properties for targetMethod.
• targetMethodConfig.scope identifies the object that the AddComponentCommunication method binds. This object must reference the targetMethod.
• targetMethodConfig.args is a list of arguments that Siebel Open UI sends to targetMethod when the AddComponentCommunication method runs.

The AddLocalString method adds a text string. It uses the following syntax:

AddLocalString(ID, custom_string)

where:

• ID is a string that you use to reference the custom_string. You can use any value for ID.
• custom_string is any text string.

  For example:

this.AddMethod("AddLocalString", function (my_text, this is my custom text) {
SiebelApp.S_App.LocaleObject.AddLocalString(my_text, this is my custom text);
return value;
});

This code adds a string named my_text that includes the following string value:

this is my custom text

The AddMethod method adds a method to a presentation model. You can use ExecuteMethod to run the method that AddMethod adds from the presentation model or from the physical renderer. If AddMethod attempts to add a new method that the predefined client already contains, then the new method becomes a customization of the predefined method, and this customization runs before or after the predefined method depending on the CancelOperation part of the return value.

A method that customizes another method can return to the caller without running the method that it customizes. To do this, you configure Siebel Open UI to set the CancelOperation part of the return value to true. You set this property on the ReturnStructure object that Siebel Open UI sends to each method as an argument. For an example that does this configuration, see Customizing the Presentation Model to Identify the Records to Delete.

The AddMethod method returns one of the following values:

• True. Added a method successfully.
• False. Did not add a method successfully.

It uses the following syntax:

AddMethod("methodName",methodDef(argument, argument_n){
}, {methodConfig:value});

where:

• methodName is a string that contains the name of the method that Siebel Open UI adds to the presentation model.
• methodDef is an argument that allows you to call a method or a method reference.
• argument and argument_n are arguments that AddMethod sends to the method that methodDef identifies.
• methodConfig is an argument that you set to one of the following values:
  • sequence. Set to one of the following values:
    • true. Siebel Open UI calls methodName before it calls the method that already exists in the presentation model.
    • false. Siebel Open UI calls methodName after it calls the method that already exists in the presentation model. The default value is false.
  • override. Set to one of the following values:
    • true. Siebel Open UI does not call the method that already exists in the presentation model. Instead, it calls the sent method, when necessary. Note that Siebel Open UI can never override some methods that exist in a predefined presentation model even if you set override to true.
    • false. Siebel Open UI calls the method that already exists in the presentation model.
  • scope. Describes the scope that Siebel Open UI must use when it calls methodDef. The default scope is Presentation Model.

The following code adds a new ShowSelection method:

this.AddMethod("ShowSelection", SelectionChange,{sequence : false, scope : this});

After Siebel Open UI adds the ShowSelection method, you can use the following code to configure Siebel Open UI to call this method. It sends a string value of SetActiveControl to the sequence and a string value of null to the scope argument. To view how Siebel Open UI uses this example, see Step 5:

this.ExecuteMethod("SetActiveControl", null)

The following code configures Siebel Open UI to attach a method. It calls this method anytime it calls the InvokeMethod method of the proxy:

this.AddMethod("InvokeMethod", function(){ }, {sequence : true});

This code sets the sequence argument to true, which configures Siebel Open UI to call the method that it sends before it calls InvokeMethod. The method that it sends gets all the arguments that InvokeMethod receives. For more information, see InvokeMethod Method for Presentation Models.

The following example overrides the predefined presentation model and runs the ProcessDrillDown method:

this.AddMethod("ProcessDrillDown", function(){
}, {override : true});

The following examples also use AddMethod:

this.AddMethod("InvokeMethod", function(){console.log("In Invoke Method of PM"), {override: true});
this.AddMethod("InvokeControlMethod", DerivedPresentationalModel.prototype.MyInvokeControlMethod,{sequence : true});

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

The AddProperty method adds a property to a presentation model. Siebel Open UI can access it through the Get method. It returns one of the following values:

• True. Added a property successfully.
• False. Did not add a property successfully.

It uses the following syntax:

this.AddProperty("propertyName", propertyValue);

where:

• propertyName is a string that identifies a property. A subsequent call to this method with the same propertyName overwrites the previous value.
• propertyValue assigns a value to the property.

For example, the following code adds the NumOfRows property and assigns a value of 10 to this property:

this.AddProperty("NumOfRows", 10);
SiebelJS.Log(this.Get("NumOfRows"));

The AddValidator method validates an event. It allows you to write a custom validation for any event. It returns one of the following values:

• true. Validated the event successfully.
• false. Did not validate the event successfully.

It uses the following syntax:

Addvalidator(siebConsts.get("event_name"), function(){custom validation}

where:

• event_name identifies the name of the event that AddValidator validates.

For example, the following code validates the control focus event:

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

You can configure Siebel Open UI to use the value that AddValidator returns to determine whether or not to stop running handlers for an event. For more information, see AttachEventHandler Method.

For more information about events, see Siebel CRM Events That You Can Use to Customize Siebel Open UI.

The AttachEventHandler method attaches an event handler to an event. It uses the following values:

• consts.get( "SWE_EXTN_CANCEL_ORIG_OP" ). If SWE_EXTN_CANCEL_ORIG_OP returns a value of true, then Siebel Open UI cancels the operation for the predefined event handler. For an example that sets the value for SWE_EXTN_CANCEL_ORIG_OP, see Attaching and Validating Event Handlers in Any Sequence.
• consts.get( "SWE_EXTN_STOP_PROP_OP" ). If SWE_EXTN_STOP_PROP_OP returns a value of true, then Siebel Open UI stops the operation for the custom event handler from propagating the customization.

The AttachEventHandler method uses the following syntax:

AttachEventHandler(event_name, function_reference);

where:

• event_name identifies the name of an event.
• function_reference identifies the name of a method that the AddMethod method adds. For example, PHYEVENT_CONTROL_BLUR. Siebel Open UI calls OnControlEvent to trigger this event, and then calls the function reference in the scope of the corresponding presentation model.

For more information about:

• An example that uses AttachEventHandler, see Example of the Life Cycle of a User Interface Element.
• Events, see Siebel CRM Events That You Can Use to Customize Siebel Open UI.
• Using AttachEventHandler, see Life Cycle Flows of User Interface Elements.
• Deriving a value, see Deriving Presentation Models, Physical Renderers and Plug-in Wrappers.

The AttachNotificationHandler attaches a method that handles the notification that Siebel Open UI calls when the Siebel Server sends a notification to an applet. It does this attachment when the notification occurs. It returns one of the following values:

• True. Attached notification handler successfully.
• False. Did not attach notification handler successfully.

It uses the following syntax:

this.AttachNotificationHandler("notification_name",handler);

where:

• notification_name is a string that includes the name or type of a notification. For example, NotifyDeleteRecord or SWE_PROP_BC_NOTI_DELETE_RECORD.
• handler identifies a notification handler that Siebel Open UI calls when notification processing finishes. For example, HandleDeleteNotification.

For more information about:

• An example that uses AttachNotificationHandler, see Customizing the Presentation Model to Handle Notifications
• Using the AttachNotificationHandle method, see Customizing Events
• How Siebel Open UI handles notifications, see Life Cycle Flows of User Interface Elements,
• Notifications, see Notifications That Siebel Open UI Supports

Assume a presentation model named pmodel.js includes an OnControlEvent method that runs a custom event handler, and that Siebel Open UI sends an eventConfig object as the last argument in the event handler call. It uses this eventConfig object in the custom presentation model to set a value for SWE_EXTN_CANCEL_ORIG_OP or SWE_EXTN_STOP_PROP_OP. This configuration allows AttachEventHandler to create multiple custom events and to stop an event handler from running.

For example, assume your customization configures Siebel Open UI to do the following:

• Derive derivedpm1.js from pmodel.js.
• Derive derivedpm2.js from derivedpm1.js.
• Derive derivedpm3.js from derivedpm2.js.
• Include an event handler for PHYEVENT_COLUMN_FOCUS in derivedpm1.js, derivedpm2.js, and derivedpm3.js.
• Use derivedpm3.js to set the AttachEventHandler to the value that SWE_EXTN_STOP_PROP_OP contains.
• Use the following code so that Siebel Open UI uses the last argument that AttachEventHandler specifies:

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

Siebel Open UI runs AttachEventHandler customizations in a LIFO (last in, first out) sequence. In this example, it uses the following sequence:

• Runs event handlers that reside in derivedpm3.js.
• Runs event handlers that reside in derivedpm2.js.
• Runs event handlers that reside in derivedpm1.js.
• Runs event handlers that reside in the predefined presentation model.

So, this example stops the custom PHYEVENT_COLUMN_FOCUS event handlers in the derivedpm2.js file and the derivedpm1.js file from running.

An event occurs when the user clicks an object or changes the focus. To manage this event, Siebel Open UI does the following work:

1. Instructs the physical renderer to call the OnControlEvent method. To make this call, it uses the event name that Siebel Open UI sends to the AttachEventHandler method and corresponding parameters.
2. Identifies the list of event handlers that it registered with the event name in the Init function of the presentation model.
3. Uses the OnControlEvent parameters from Step 1 to call each of the event handlers that it identified in Step 2.
4. Finishes running all the event handlers, and then sends a return value to the object that called OnControlEvent.

The AttachPMBinding method binds a method to an existing method. Siebel Open UI calls the method that it binds when it finishes processing this existing method. The AttachPMBinding method returns one of the following values:

• True. The bind succeeded.
• False. The bind failed.

It uses the following syntax:

this.AttachPMBinding("method_name",function(){SiebelJS.Log("method_to_call");},{when : function(conditional_function){return value;}});

where:

• method_name is a string that identifies the name of a method.
• method_to_call identifies the method that Siebel Open UI calls when it finishes processing method_name.
• conditional_function identifies a function that returns one of the following values:
  • true. Calls the AttachPMBinding method.
  • false. Does not call the AttachPMBinding method.

For an example that uses AttachPMBinding, see Customizing the Physical Renderer to Refresh the Carousel.

For more information about using the AttachPMBinding method, see Configuring Siebel Open UI to Bind Methods and Life Cycle Flows of User Interface Elements.

The AttachPostProxyExecuteBinding method binds a method that resides in a proxy or presentation model to a PostExecute method. Siebel Open UI finishes the PostExecute method, and then calls the method that AttachPostProxyExecuteBinding identifies. It uses the following syntax:

this.AttachPostProxyExecuteBinding("method_to_call", function(methodName, inputPS, outputPS){"binder_configuration";return;});

where:

• method_to_call is a string that identifies the method that Siebel Open UI calls.
• binder_configuration is a string that identifies code that Siebel Open UI runs after the applet proxy sends a reply.

For more information, see Refreshing Custom Events and PostExecute Method.

In the following example, the user clicks the New button in an applet, Siebel Open UI runs the NewRecord method, and then the client receives the reply from the Siebel Server. In this situation, you can use the following code to run some logic in the presentation model after Siebel Open UI runs the PostExecute method as part of the element life cycle:

this.AttachPostProxyExecuteBinding("NewRecord", function(methodName, inputPS, outputPS){"Do Something for New Record";return;});

The following code runs this same logic in the presentation model for all methods:

this.AttachPostProxyExecuteBinding("ALL", function(methodName, inputPS, outputPS){"Do Something for all methods";return;});

For more information, see NewRecord Method.

For more examples that use AttachPreProxyExecuteBinding and AttachPostProxyExecuteBinding, see Customizing the Presentation Model to Call the Siebel Server and Delete a Record and Calling Methods.

The AttachPreProxyExecuteBinding and AttachPostProxyExecuteBinding methods provide a generic way to do more processing than the AttachNotificationHandler method provides before or after the proxy finishes processing the reply from a method that the client or the Siebel Server calls. A method might cause Siebel Open UI to create a notification from the Siebel Server that does more post-processing than the client proxy requires. This situation can occur with a custom method that you implement on the Siebel Server. For example, with an applet, business service, or some other object type. For more information, see AttachNotificationHandler Method.

Siebel Open UI sends a notification only for a typical modification that occurs in the predefined product. For example, a new or deleted record or a modified record set. Siebel Open UI might not be able to identify and process the correct notification. For example, you can configure Siebel Open UI to make one call to the WriteRecord method from the client, but the server business logic might cause this method to run more than one time. Siebel Open UI might receive notifications for any WriteRecord method that occurs for a business component that it binds to the current user interface. These notifications might contain more information than the reply notification requires. For more information, see WriteRecord Method,.

The AttachPreProxyExecuteBinding method binds a method that resides in a proxy or presentation model to a PostExecute method. Siebel Open UI calls this method, and then runs PostExecute. The AttachPreProxyExecuteBinding uses the same syntax and arguments that the AttachPostProxyExecuteBinding method uses, except you configure Siebel Open UI to call the AttachPreProxyExecuteBinding method. For more information, see AttachPostProxyExecuteBinding Method.

The ExecuteMethod method runs a method. You can use it to run a predefined or custom method that the presentation model contains. It makes sure Siebel Open UI runs all dependency chains for the method that it calls. For more information about dependency chains, see About Dependency Injection.

If the method that ExecuteMethod specifies:

• Exists. It returns a value from the method that it specifies.
• Does not exist. It returns the following string:

  undefined

It uses the following syntax:

this.GetPM().ExecuteMethod("method_name", arguments);

where:

• method_name is a string that identifies the name of the method that ExecuteMethod runs. You must use the AddMethod method to add the method that method_name specifies before you run ExecuteMethod. If the method that method_name specifies:
  • Exists. Siebel Open UI calls the method that method_name specifies, sends the arguments, gets the return value, and then sends this return value to the object that called the ExecuteMethod method.
  • Does not exist. The ExecuteMethod method does nothing.
• arguments includes a list of one or more arguments where a comma separates each argument. ExecuteMethod sends these arguments to the method that method_name specifies. It sends these arguments in the same order that you list them in this argument list.

For examples that use InvokeMethod, see Customizing the Presentation Model to Delete Records and Customizing the Presentation Model to Handle Notifications.

For more information about using this method, see Life Cycle Flows of User Interface Elements.

The Get method returns the value of the property that Siebel Open UI adds through the AddProperty method. If Siebel Open UI sends a method in the propertyValue argument of the AddProperty method, then it calls the Get method, and then sends the return value to the method that calls the Get method. For an example that uses the Get method, see Customizing the Presentation Model to Delete Records. For more information about using this method, see Life Cycle Flows of User Interface Elements.

The GetCtrlTemplate method gets the template for a control, and then uses values from this template to create an object. It uses values from this template to set the default values and the format for the property set that this control uses. It returns nothing. It uses the following syntax:

GetCtrlTemplate ("control_name", "display_name", consts.get( "control_type" ), column_index);

where:

• control_name specifies the name of the control.
• display_name specifies the label that Siebel Open UI displays in the client for this control.
• control_type specifies the type of SWE control, such as SWE_CTRL_TEXTAREA. You can specify one of the following values:
  • SWE_CTRL_URL
  • SWE_CTRL_TEXTAREA
  • SWE_CTRL_TEXT
  • SWE_CTRL_DATE_TZ_PICK
  • SWE_CTRL_DATE_TIME_PICK
  • SWE_CTRL_DATE_PICK
  • SWE_CTRL_CHECKBOX
  • SWE_CTRL_CALC
  • SWE_CTRL_COMBOBOX
  • SWE_CTRL_PWD
• column_index is an integer that specifies the physical location in the list control.

For example, the following code gets the template for the TestEdit control:

GetCtrlTemplate ("TestEdit", "Test Edit", consts.get( "SWE_CTRL_TEXTAREA" ), 1);

The Init method allows you to use different methods to customize a presentation model, such as AddMethod, AddNotificationHandler, AttachPMBinding, and so on. It uses the following syntax:

Init()

For an example that uses Init, see Step 2.

You must not configure Siebel Open UI to override any method that resides in a derived presentation model except for the Init method or the Setup method. For more information, see Deriving Presentation Models, Physical Renderers and Plug-in Wrappers.

You must configure Siebel Open UI to do the following:

• Call the Init method in the predefined presentation model before it calls the Init method in the derived presentation model.
• Call the Setup method in the predefined presentation model before it calls the Setup method in the derived presentation model. For more information, see Setup Method for Presentation Models.

The OnControlEvent method calls an event. It uses the following syntax:

OnControlEvent(event_name, event_arguments)

where:

• event_name identifies the name of an event. You must use event_name to send an event.

For more information about:

• Examples that use OnControlEvent, see the following topics:
  • Modifying CSS Files to Support the Physical Renderer
  • Adding Custom User Preferences to Applets.
• How Siebel Open UI uses OnControlEvent, see the following topics:
  • How Siebel Open UI Uses the Init Method of the Presentation Model
  • Siebel CRM Events That You Can Use to Customize Siebel Open UI
  • Life Cycle Flows of User Interface Elements

The SetProperty method sets the value of a presentation model property. It returns one of the following values:

• True. Set the property value successfully.
• False. Did not set the property value successfully.

It uses the following syntax:

SetProperty(property_name, property_value)

where:

• property_name specifies the name of the property that SetProperty sets.
• property_value specifies the value that SetProperty sets for property_name.

If the property that the SetProperty method references does not exist, then Siebel Open UI creates this property and sets the value for it according to the SetProperty method. You can also use the AddProperty method to add a property.

For examples that use SetProperty, see the following topics:

• Customizing the Presentation Model to Delete Records
• Customizing the Presentation Model to Call the Siebel Server and Delete a Record
• Text Copy of Code That Does a Partial Refresh for the Presentation Model
• Adding Custom User Preferences to Applets
• Using Custom JavaScript Methods
• Customizing Siebel Pharma for Siebel Mobile Disconnected Clients

The Setup method extracts the values that a property set contains. Siebel Open UI calls this Setup method when it processes the initial reply from the Siebel Server. It uses the following syntax:

Setup(property_set)

where:

• property_set identifies the property set that Siebel Open UI uses with the corresponding proxy object. It contains the property set information for the proxy and any custom property set information that Siebel Open UI added through the presentation model that resides on the Siebel Server. If Siebel Open UI must parse a custom property set, then this work must occur in the Setup method for the derived presentation model. For more information, see Deriving Presentation Models, Physical Renderers and Plug-in Wrappers.

For example, the following code identifies the childPropset property set:

extObject.Setup(childPropset.GetChild(0));

For more information about:

• How Siebel Open UI uses this Setup method, see Summary of Presentation Model Methods. GetChild Method.
• Examples that use the Setup method, see Customizing the Setup Logic of the Presentation Model and Adding Presentation Model Properties That Siebel Servers Send for Applets.
• The Setup method that Siebel Open UI uses with components, see Setup Method for Components.