Guidelines for Customizing Siebel Open UI

This topic describes guidelines for configuring Siebel Open UI. It includes the following information:

• "Guidelines for Customizing Presentation Models"

• "Guidelines for Customizing Physical Renderers"

• "Guidelines for Customizing Plug-in Wrappers"

• "Guidelines for Customizing Presentation Models and Physical Renderers and Plug-in Wrappers"

Some Siebel Open UI customizations use the same configuration that a Siebel Business Application uses. For example, you can use the information that Configuring Siebel Business Applications describes to configure the following items in Siebel Open UI:

• List applets

• Form applets

• Views that contain more than one applet

• Applet controls and list columns

Guidelines for Customizing Presentation Models

It is recommended that you apply the following guidelines if you configure a presentation model:

• Make sure you customize Siebel Open UI so that the user-interface state is separate from the rendering of this state. The guidelines in this topic describe how to do this.

• Add a new presentation model only after you consider all other customization options, such as modifying code in a Siebel Web Template file or using Siebel Tools to modify an object. To examine some examples that do not modify the presentation model, see Chapter 5, "Customizing Siebel Open UI."

  A presentation model implements the entire abstraction of the user interface content, so the predefined implementation of a presentation model implements the predefined abstraction. There are only a few types of basic user interface abstractions, such as single record, list, tree, and so on. It is recommended that you use a predefined presentation model for each of these basic abstractions that Oracle provides you.

• Make sure Siebel Open UI models all the state variables that it requires to achieve a rich client behavior, and that it models these state variables as presentation model properties. These properties can reside in the presentation model on the client, or the Siebel Server can provide them from an applet. You can add methods that modify these properties and that manage the state changes after you configure Siebel Open UI to add them. Siebel Open UI typically calls these methods due to a user action, or if the server sends a notification. If a method modifies the logical state of the user interface, then Siebel Open UI uses the AttachPMBinding method to add a binding trigger to the physical renderer. This trigger binds the modified state to the physical user interface. For more information, see "AttachPMBinding Method".

Siebel Open UI strictly defines each life cycle method. To help make sure your implementation is clean and readable, it is recommended that you use the following guidelines:

• Make sure Siebel Open UI uses all presentation model state variables as properties. You must use the AddProperty method to create these properties. You must not use ordinary JavaScript variables to create these properties.

• Use methods to implement all state changes of the presentation model. Use the AddMethod method to create these methods.

• Make sure Siebel Open UI uses the AttachEventHandler method to bind each method that the presentation model contains to an event that the physical renderer contains. Each event occurs as the result of some physical user action. This configuration makes sure Siebel Open UI binds each user action to the required logic and modifies the user interface state. For more information, see "AttachEventHandler Method".

• A presentation model method can start a call to the Siebel Server, and then the server sends a reply to this method. Siebel Open UI handles these calls asynchronously, except for Siebel browser scripts that run in high interactivity clients. For more information, see "About Synchronous and Asynchronous Requests".

• When Siebel Open UI sends a reply, it includes all modifications that occur in the business component layer. It includes these modifications in the reply that it sends in a Notification property set. You must use the AttachNotificationHandler method to add this notification. For more information, see "Notifications That Siebel Open UI Supports":

  • Siebel Open UI packages a reply from the server for any predefined type of request. It includes this package in a predefined reply property set. You must use the AttachPSHandler method to add the handler for any property set type that the server sends.

  • You must use the AttachPostProcessingHandle method to add any post-processing handler that does follow up logic on a server request, such as a NewRecord request. You can add this logic after Siebel Open UI finishes processing the reply for this request. Setting the focus for a control is an example of this kind of configuration.

• Siebel Open UI does the initial setup of the presentation model when it initializes the Siebel view or application, depending on whether the user interface object resides inside or outside of the view. The server sends a property set that includes all the initialization attributes. The proxy uses most of these attributes, but you must use the AddProperty method to get the values that the presentation model requires to set and store the state.

• You must use the following methods in the physical renderer the first time Siebel Open UI renders the user interface:

  • BindEvents. Binds the presentation model methods to the appropriate events on a control. For more information, see "BindEvents Method".

  • BindData. Accesses the presentation model properties, and then sends them to the control through the methods that this control exposes. For more information, see "BindData Method".

• You must configure Siebel Open UI to bind any state changes to the presentation model that occur after the physical renderer finishes the initial rendering. To do this, you configure Siebel Open UI to call the AttachPMBinding method on the physical renderer. This configuration specifies the method that the physical renderer must call or the properties that it must access so that it can send data back to the control. This configuration allows Siebel Open UI to render the user interface after it modifies the presentation model state.

Guidelines for Customizing Physical Renderers

It is recommended that you apply the following guidelines if you configure a physical renderer:

• Use a physical renderer only to implement methods that render the presentation model state:

  • Do not include any other logic in a physical renderer.

  • Do not include business logic that modifies the user interface state.

  • Do not include manipulations or life cycle control of individual controls or fields. It is recommended that those types of customizations should be maintained separately, in the Plug-in Wrapper.

  • Only use a physical renderer to send user action events to the presentation model, and use the presentation model to do all the work that is necessary to modify a state.

  • Allow the physical renderer to rebind the new presentation model state to the rendered user interface only after the presentation model finishes modifying the state of the logical user interface.

• Do not use a physical renderer to add any presentation attributes to the Document Object Model (DOM). Example attributes include position, color, or any other styling. To modify a presentation attribute, you must attach or detach a style that you define in a CSS file.

• Configure Siebel Open UI to do all rendering only in physical renderers or plug-in wrappers. It is strongly recommended that you do not configure Siebel Open UI to do direct DOM manipulation. If you cannot avoid direct DOM manipulation, then you must do this manipulation in a physical renderer or in a plug-in wrapper. Configure Siebel Open UI to send data, metadata, or state information to controls only from a physical renderer. For more information, see "About Objects and Metadata".

• In most situations, if you add a presentation model, then you must also add a corresponding physical renderer. You typically use a presentation model to add custom logic in the client. This logic typically determines a physical behavior that requires a physical renderer to do the rendering. For example, in most situations, you cannot configure a predefined applet that also renders custom logic. Siebel Open UI structures custom JavaScript logic in the presentation model and physical renderer as a customization of predefined Siebel Open UI. This structure allows Siebel Open UI to use JavaScript and to use other logic that a predefined Siebel Open UI implementation provides, such as events, Siebel arrays, and so on. It is not recommended that you configure JavaScript that is independent of Siebel Open UI, and that also modifies Siebel CRM data or physical behavior.

Guidelines for Customizing Plug-in Wrappers

It is recommended that you apply the following guidelines when configuring a plug-in wrapper:

• Use a plug-in wrapper exclusively to implement methods that manage the life cycle of an individual control or field.

• Do not include any other logic in a plug-in wrapper.

• Do not include business logic that modifies the user interface state.

• Use a physical renderer, exclusively, to send user action events on a field to the presentation model. Use the presentation model to do all the actions that require modifying a state.

• Allow the plug-in wrapper to rebind the new presentation model state to the rendered control only after the presentation model finishes modifying the state of the logical user interface.

• Do not use a plug-in wrapper to add presentation attributes to the Document Object Model (DOM). Examples of these types of attributes include: position, color, or any other styling attribute. To modify a presentation attribute, you must attach or detach a style that you define in a CSS file.

• In most situations, if you add a plug-in wrapper, then you must also add a corresponding physical renderer that interacts with the plug-in wrapper. Typically a plug-in wrapper is used to add custom logic to controls in the client. This logic determines a physical behavior that requires a physical renderer to do the handling for this wrapper.

Guidelines for Customizing Presentation Models and Physical Renderers and Plug-in Wrappers

It is recommended that you apply the following guidelines if you configure the presentation model and physical renderer for a client object:

• Determine the following items for any element that you intend to customize:

  • The presentation model you must use

  • The plug-in wrapper you must use and the physical renderer that you must use with the presentation model

• Configure the manifest so that Siebel Open UI can identify the JavaScript files it must download to the client so that it can render the user interface element. For more information, see "Configuring Manifests".

• Modify the physical renderer and presentation model for user interface objects that do not reside in a view, such as navigation tabs. Only one of these elements resides on a single Siebel page, and they do not vary during a Siebel session. So, you can configure the physical renderer and the presentation model for each of these elements in the manifest.

• You must place all custom presentation models, physical renderers and plug-in wrappers in the custom folder. For more information about this folder, see "Organizing Files That You Customize".