Siebel Open UI Extensibility Part 2: The Google Maps Example (Updated)

Welcome to part 2 of our small series on Open UI scripting. In the previous article, we have discovered the scaffolding for a presentation model. Today, we will talk about the physical renderer file and we will see that they are quite similar in nature.

Instead of boring you to death with another boilerplate, I thought it would be worthwhile to apply one of the most prominent requirements to Siebel Open UI...

Of course, we are talking about displaying an account's primary address in a (Google) map. Siebel Essentials veterans might guess where this is going ;-)

During the early phase of Open UI development, I had access to some beta systems which sported a map icon next to the Postal Code field on the account form applet. On hovering or clicking the icon, the map was displayed in a floating window.

Later, this became one of the practice examples for teaching partners and internal employees how to configure Open UI. I took this example and expanded it a bit. The example also shows how to integrate third party libraries.

So here is what we want to achieve:

Google map in Siebel Open UI. Click to enlarge.

And here is the cookbook:

1. Create the presentation model
2. Create the physical renderer
3. Update the extension mapping file
4. Add third party libraries (optional)
5. Update the custom manifest file
6. Add custom styles (optional)
7. Test

And here we go:

1. Create the Presentation Model

The general structure of a presentation model file has been laid out in the previous post. By obeying those rules, we create the necessary code to implement a new class named ALEXMapHoverPM. So the first part of the file will look like this:

(Don't worry, I uploaded all files to Google Drive, so you can get them)

In the presentation model class, we add the stPostalCodeHTML property which will hold the replacement HTML code for the Postal Code control.

this.AddProperty("stPostalCodeHTML");

Additionally we add the following methods:

//add two standard methods "ShowSelection" and "FieldChange"

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

this.AddMethod("FieldChange",OnFieldChange,{sequence:false, scope:this});

//add a custom method createMapHTML; must use this.ExecuteMethod to call!

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

Note that we add a custom method named createMapHTML which will implement the HTML code generation. We also add the two standard methods ShowSelection and FieldChange to be able to re-run our code every time a new record is selected or a field value is changed.

The code for the two standard methods is quite simplistic:

function SelectionChange()

{

     //execute the createMapHTML function

     var stPostalCodeHTML = this.ExecuteMethod("createMapHTML");

            

     //set the stPostalCodeHTML property

     this.SetProperty("stPostalCodeHTML",stPostalCodeHTML);

}

function OnFieldChange(control,value)

{

    if (control.GetName() === "PostalCode")

    {

        var stPostalCodeHTML = this.ExecuteMethod("createMapHTML");

        this.SetProperty("stPostalCodeHTML",stPostalCodeHTML);

    }

}

As we can see, the SelectionChange function executes the createMapHTML method to populate the stPostalCodeHTML property. So does the OnFieldChange function, but only when the PostalCode control is the one which undergoes a value change.

And here is the createMapHTML function in all its glory:

function createMapHTML ()

{

    //the map URL goes here (note 'output=embed' for Google Maps)

    //good place to try other map providers like Bing, Nokia or Oracle

    var mapURL = "http://maps.google.com/maps?z=14&ie=UTF8&hl=en&output=embed&q=";

    //get a handle on the applet controls

    var controls = this.Get("GetControls");

    //get the address field values and concatenate

    var ctrlStreetAddress = controls["StreetAddress"];

    var ctrlPostalCode = controls["PostalCode"];

    var ctrlCity = controls["City"];

    var ctrlCountry = controls["Country"];

    var stStreetAddressValue = this.ExecuteMethod("GetFieldValue",ctrlStreetAddress);

    var stPostalCodeValue = this.ExecuteMethod("GetFieldValue",ctrlPostalCode);

    var stCityValue = this.ExecuteMethod("GetFieldValue",ctrlCity);

    var stCountryValue = this.ExecuteMethod("GetFieldValue",ctrlCountry);

    var stFullAddress = stStreetAddressValue + "," + stPostalCodeValue + "," + stCityValue + "," + stCountryValue;

    //get the element ID of the postal code field

    var fieldElemId = ctrlPostalCode.GetInputName();

    //build the HTML for the postal code filed

    var stPostalCodeHTML = '<input type="text" name="' + fieldElemId + '" value="' + stPostalCodeValue + '" style="float:left;width:105px;height:24px"></input><a class="iframe" href="' + mapURL + stFullAddress + '"><img name="myMapsIcon" src="images/map.gif" height="16" width="16" style="float:right;"></img></a>';

        

      return stPostalCodeHTML

}

The function basically does the following:

1. Define the base URL for the map provider (Google maps in the example).
2. Use the GetControls property to get an array of all current applet controls.
3. Access the address controls (must use the Control names defined in the repository).
4. Use the GetFieldValue method to get the address control values.
5. Concatenate the address data into a comma separated string.
6. Use the GetInputName method to get the DOM element Id of the postal code control.
7. Generate the replacement HTML for the postal code field by concatenating HTML with variable values. The resulting HTML is a textbox with the postal code (which is the original control) plus a map icon which is wrapped in a hyperlink (class="iframe") to the full map URL.

As the code is for educational purposes, it is quite verbose and will likely be different in your implementation.

If you use any custom icon, you must of course upload it to the PUBLIC/#language#/IMAGES directory.

You can download the full presentation model file here.

We must save any custom JavaScript file for Open UI in the following folder location:

PUBLIC\#language#\#build#\SCRIPTS\siebel\custom

For the example, I saved the file as alexmaphoverpm.js.

2. Create the Physical Renderer

The physical renderer class is contained in a separate file and is responsible for manipulating the DOM so that the desired UI behaviour is achieved. The basic skeleton of a physical renderer file is strikingly similar to a presentation model. Below is a screenshot of the scaffolding. You may want to download the full example file here.

The main difference is that a physical renderer will use the GetPM method to access the presentation model framework and one of the first methods to be used is the AttachPMBinding method. The purpose of this method is to create a binding between a physical renderer function and a property. In our example we bind the stPostalCodeHTML property to the MapHover function. This causes the MapHover function to be executed each time the stPostalCodeHTML property is changed by the presentation model.

In addition, we use the SiebelJS.Extend method to inherit the base functionality of the pre-built PhysicalRenderer class.

After providing the base scaffolding, we can write the custom MapHover function:

function MapHover()

{

    //get the controls

    var controls = this.GetPM().Get("GetControls");

    var ctrlPostalCode = controls["PostalCode"];

    var stPostalCode = ctrlPostalCode.GetInputName();

    var stPostalCodeHTML = this.GetPM().Get("stPostalCodeHTML");

    //jQuery magic...

    $('input[name="' + stPostalCode + '"]').parent().html(stPostalCodeHTML);

    

    //colorbox magic...

    $(".iframe").colorbox({iframe:true,width:"65%",height:"75%",opacity:0.5});

}

The function does the following:

1. Use the presentation model's (GetPM) Get method to read the GetControls property.
2. Get the DOM element Id of the postal code control.
3. Get the value of the stPostalCodeHTML property.
4. Use the $() method of the jQuery library to manipulate the postal code control so that the original HTML is replaced with the generated HTML code. (jQuery comes with Open UI so we can use the full jQuery API).
5. Optionally, play with third party or custom libraries (colorbox in the example) to accomplish a slick and lean appearance.

You can find the full example physical renderer file here.

Again, we must save the file in the following folder location:

PUBLIC\#language#\#build#\SCRIPTS\siebel\custom

For the example, I saved the file as alexmaphoverpr.js.

3. Update the Extension Mapping File

Now we must associate the applet(s) with the extended presentation model and physical renderer files. We have two choices to do so:

1. Modifying the manifest_extensions.map file in the OBJECTS folder
2. Adding user properties in the Siebel Repository

The recommended (as per the Configuring Open UI guide) approach is to modify the file named manifest_extensions.map. This file is located in the OBJECTS folder of the Siebel Server or Developer Web Client. The file contains one section for presentation model mappings and one for physical renderer mappings. The syntax within the sections is Applet or View = Key, where Key must match exactly the strings we use in the RegisterConstructorAgainstKey functions in our code.

Update: As a dear commenter pointed out some problems with this extension, I re-tested against a fresh install and encountered some strange behavior of the manifest_extensions.map file.

We would expect that a valid manifest_extensions.map file would look as follows:

But on some occasions this might not work as expected. If this is the case, add an empty [Presentation_Model] section to the beginning of the file so that it looks similar to the following:

Strange enough, but this rectifies the problems. (End of update)

The main benefit of using the bespoke approach is that we gain complete independence from the Siebel Repository and do not have to compile or deploy the SRF file.

The second (alternative) way to "tell" the applet which presentation model and physical renderer to use is by setting the Physical_Renderer and Presentation_Model applet user properties (which are of course only available at patch level 8.1.1.9 or 8.2.2.2 and higher).

The values of the user properties must match exactly the strings we use in the RegisterConstructorAgainstKey functions. So the correct values for our example would be as follows:

As we can observe, the example is built on top of the SIS Account Entry Applet which is the default applet in the SIA Account list and detail views.

Of course, we must compile the applet after the change and distribute the SRF file when we chose this approach.

4. Add Third Party Libaries (optional)

If you used third party (or custom) libaries which are not yet part of the framework, you must add them to the following location:

PUBLIC\#language#\#build#\SCRIPTS\3rdParty

In the example, we use the colorbox libary so we must extract the downloaded library files to the colorbox subdirectory.

5. Update the Custom Manifest File

Siebel Open UI uses a set of XML files to link the names we use in the applet user properties to the physical files which store the JavaScript. These files are found in the OBJECTS directory and are named custom_manifest.xml and core_manifest.xml. The custom_manifest.xml file must be modified for any custom presentation model or phyiscal renderer.

So to be in tune for our example, we open the custom_manifest.xml file in the OBJECTS directory (making a backup copy before is a good idea) and add a new <KEY> element to the <KEY_COMMON> parent element. After the change, the file looks like this:

The Name attribute of the KEY element must match exactly the value of the Presentation_Model key name we defined earlier.

Note that the KEY element contains FILE_NAME elements which reference the custom, third-party and base files involved in the implementation. The base files applet.js and pmodel.js include the pre-defined presentation model methods we use in our code, so we must include them.

Next, we find the <PLATFORM_KEY_SPECIFIC><PLATFORM Name="Desktop"> section and add a new KEY element with the necessary FILE_NAME child elements to represent the files involved in the custom physical renderer.

The Name attribute must now of course match exactly the value of the Physical_Renderer key name we defined earlier.

The FILE_NAME child elements reference the custom, third-party and base files involved. The phyrenderer.js file is the out-of-the-box definition of the physical renderer and must always be included.

6. Add Custom Styles (optional)

If we use custom CSS styling, we must edit the theme.js and themetree.js (Note: themetree.js might not exist in your build, so just stick to theme.js) files (located in the SCRIPTS/siebel folder and add a reference to the custom or third-party style sheet files to the css section of all defined themes. After the modification, the files look similar to the following:

In the example, we add a new line named "colorbox" (we use this name as a reference in the physical renderer file) to every theme defined in the files. The value of the entry is a reference to the .css file which contains the styles we want to use in the implementation.

7. Test

Before we can test, we must ensure that all repository changes (usually only applet user properties) are compiled and the SRF is distributed. In addition, we must clear the cache of our browser and then launch the client.

If all goes well, we should now see a map icon appear next to the Postal Code control in the account form applet. Hovering over the icon should allow us to see the URL in the browser status bar.

And finally clicking on the icon should open a "colorboxed" frame displaying the map:

Summary

The above example, together with the previous post, demonstrates the basic steps to extend the Siebel CRM Open UI framework with custom UI-based functionality.

We must of course bear in mind that displaying a map (as shown in the example) is also possible in a classic or Open UI client (as shown here) using traditional techniques such as Symbolic URLs or calculated fields, etc.

For your convenience, here are the links to the JavaScript files and the colorbox libary, just in case you want to attempt this on your own ;-)

Presentation Model alexmaphoverpm.js

Physical Renderer alexmaphoverpr.js

colorbox library by Jack Moore

have a nice day

@lex