Google Maps in Siebel (Open UI): The Penultimate Edition - Part 2

Welcome to the second part of our 'penultimate' edition of Google Maps in Siebel Open UI.

In the first part, we focused on the scaffolding, used templates to create a custom PM and PR for the SIS Account Entry Applet and downloaded and registered the colorbox plugin.

Today we will look at the actual implementation, starting with some requirements:

• As stated in part 1, the code should be generic enough to work with all form applets that display address data
• The solution should be SRF-independent.
• A clickable map icon should be displayed next to the address fields.
• When the icon is clicked, the map of the address displayed in the applet should be shown in a colorbox iFrame.

So, let's get to work:

4. Implement the Presentation Model

The purpose of a presentation model is to capture the business logic behind the scenes. In our example, the PM's task will be to extract the address information and create the link which leads to the map vendor's web site.

The following screenshot shows the custom PM's Init method and two "event handlers":

Click to enlarge.

The above code does the following:

• Declare a new property "sMapHTML" to hold the HTML code for the link.
• Declare handler methods for the ShowSelection and FieldChange API methods. Remember that "sequence:false" means "post".
• Declare a custom method CreateMapHTML
• The two "post" event handler methods simply invoke the CreateMapHTML function which returns the link HTML and then set the sMapHTML property value.

And here is the CreateMapHTML function in all its glory (see below for details):

Click to enlarge.

The above function does the following:

• Declare the map base URL and parameters.
• Get the controls for the current applet
• Declare an object addressControls to hold the address related controls. Initialize each element with a "search string" such as "addr" or "postal". These search strings are meant to be used to locate address related controls in the applet. This is an experimental SRF-independent alternative to applet user properties and is of course problematic when address controls have "meaningful" names such as "HTML Text 2" or similar...
• Iterate through the controls of the applet and compare the name of each control to the "search string". If the control name contains the search string, the control object will be added to the addressControls object.
• Store the addressControls object as a property for easy access from within the PR.
• Verify that we actually have an address using the control representing the street address.
• Concatenate all address fields to a full address string to be used on the map page.
• Generate the image link HTML using the full address string.

As discussed above, this educational example tries to demonstrate SRF-independency. If the names of the applet controls do not contain the "search strings", the above solution will not work. I have demonstrated how to use applet user properties to "broadcast" information from the repository to the PM in an earlier post.

In addition, one might want to consider externalizing all hardcoded stuff such as the map base URL, its parameters and the HTML snippets. Using constants similar to the as-delivered Open UI API would be a good idea.

The example presentation model file can be downloaded here.

5. Implement the Physical Renderer

Now it's time for the PR code. First, we modify the line which calls the define function to resemble the following (modifications in bold font).

define("siebel/custom/GoogleMapBoxPR", ["siebel/phyrenderer","siebel/custom/colorbox/jquery.colorbox-min"], function(){

This modification ensures that the colorbox library is always loaded with the physical renderer. This is an alternative to registering the library with the manifest and ensures that the colorbox code is only loaded when it is really needed.

The following screenshot shows the remainder of the PR code (explanation below):

Click to enlarge.

The above code does the following:

• In the PR's Init method, use the AttachPMBinding method to attach the local ShowMapIcon method to the sMapHTML property. This ensures that the ShowMapIcon method is invoked every time the property is altered.

The ShowMapIcon method does the following:

• Get the HTML generated by the PM
• Remove any current instances of the image link using the anchor's name attribute.
• Get the addressControls object from the property.
• Obtain the object representing the street address control.
• Get the value of the control's name attribute.
• Insert the HTML string after the control.
• Call the colorbox method upon the link. Note the iframe:true specification which is required for Google maps.

The example physical renderer file can be downloaded here.

6. Test

The result of the above code is a map icon displayed next to the street address control in a form applet:

The icon will only be displayed if there is an address available.
When the icon is clicked, a colorbox iFrame will open and display the map:

Click to enlarge.

To test the genericity of the code, register the PM and PR with other form applets (such as the Contact Form Applet) which display address data. Again, the code is experimental and not production-ready. Using applet user properties to specify the address field names might be a much safer way but alas is SRF dependent.

Summary

Thanks again to Mattias for the inspiration to bring the Google maps example to IP 2013 (or higher). I took the liberty of tweaking the requirements hoping to trigger some out-of-the-box thinking.

As a courtesy, you can download the PM and PR code (code examples provided on Siebel Essentials are for educational purposes only! Do not use this code in production! If you do so, it is at your own risk!) here:

The example PM can be downloaded here.
The example PR can be downloaded here.

What is your approach to the "maps requirement"? Please find the comments.

have a nice day

@lex

Google Maps in Siebel (Open UI): The Penultimate Edition - Part 1

Displaying Siebel address data in a Google map seems to become one of the most discussed topics here on Siebel Essentials. Just recently, I received a friendly email from Mattias Johansson from Accelsior Corporation who published a follow-up on one of my posts, upgrading the pre-IP 2013 example in the post to version 8.1.1.11 or higher (click here to access Mattias' original article).

I really liked Mattias' initiative and decided to rewrite the Google maps example for Siebel Open UI again on my own. In the below article I will discuss the steps to achieve the following in IP 2013 or higher:

Siebel Open UI with a Google map in a colorbox iFrame.

To spice things up a bit, I added the following ingredients:

• The code should be generic, i.e. it should work on any form applet displaying address data.
• There should be no dependency on the SRF.
• It should be easy to "switch" to another map engine.
• Colorbox should be used for displaying the map.

And here are the steps I followed to implement this:

1. Create a basic Presentation Model and Physical Renderer from templates
2. Register the new PM and PR with a test applet
3. Take care of third party code
4. Implement the PM
5. Implement the PR
6. Test

Let's get started.

1. Create a basic Presentation Model and Physical Renderer from Templates

If you spent a bit of time with the Siebel Open UI JavaScript API, you will by now have created templates for a "basic" Presentation Model (PM) and Physical Renderer (PR). If not, it is about time because using a template saves you a lot of time.

For the benefit of my readers, I have made example templates for PR and PM available.

Click here for a sample PR template
Click here for a sample PM template

(Needless to say: using this - and any other bits of - code from this site comes at your own risk)

To start from the template files, open them in a script editor of your choice and save them using a unique file name in the /siebel/custom folder of your Siebel Developer Web Client installation. For my example I choose these file names:

GoogleMapBoxPM.js
GoogleMapBoxPR.js

Next, use the find and replace feature of the editor to replace all occurrences of "PMTemplate" with your unique name (sans ".js") such as GoogleMapBoxPM in the PM template. Repeat the procedure in the PR Template (using "PR" as the suffix, of course).

2. Register the new PM and PR with a Test Applet

Before you start working on the implementation, you should make sure that your new PM and PR files are properly loaded. To accomplish this, you register them with a test applet. For our example, we can choose the SIS Account Entry Applet, a standard applet which exposes address fields for an account.

To register a custom PM or PR with an applet, follow the steps below

1. Navigate to the Administration - Application screen.
2. Navigate to the Manifest Files view.
3. In the Files list, create a new record and enter (or rather copy & paste) the relative path to the new file, for example: siebel/custom/GoogleMapBoxPM.js
4. Navigate to the Manifest Administration view.
5. In the UI Objects list, create a new record with the following values:

• Type = Applet
• Usage Type = Presentation Model
• Name = SIS Account Entry Applet

6. In the Object Expression list, create a new record with the following values :

• Expression = Desktop (use the picklist)
• Level = 1

Note: You might want to use a different expression or none at all, depending on your needs. 

7. In the Files list, click the Add button and associate the file you registered in step 3.
8. Log out of the application and log back in again.
9. Navigate to a view which contains the applet specified in step 5.
10. Open the browser's JavaScript console
11.Verify that the console messages appear as implemented in the template file. Alternatively use the Sources tab of the browser developer tool to verify the presence of the custom file.

Repeat the above procedure for the physical renderer file. Make sure that you use "Physical Renderer" as the usage type in step 5.

Compare your settings with the following screenshot:

Click to enlarge

3. Take Care of Third Party Code

As our example uses Jack Moore's colorbox plugin for jQuery, we have to download it and copy all the necessary files to the right places. Here is a summary of the steps:

1. Go to http://www.jacklmoore.com/colorbox and download the .zip archive.
2. Extract the archive to a temporary folder.
3. Copy the jquery.colorbox-min.js file to the /siebel/custom/colorbox folder (create the colorbox folder).
4. Take a look at the examples and choose one that fits your needs.
5. From the examples folder of your choice (e.g. example1), copy the colorbox.css file to the /PUBLIC//FILES/custom folder (create the custom folder if necessary).
6. Copy the exampleN/images folder to the /PUBLIC//FILES/custom folder.

The colorbox plugin comes with its own style sheet which we must register as well. To do so, we must either create a custom theme.js file or edit the existing one. The code we need to add to the custom theme.js file is the following:

SiebelApp.ThemeManager.addResource(

    "GRAY_TAB",

    {

        css : {

            colorbox_theme:"files/custom/colorbox.css"

        }

    }

);

The above code calls the addResource method of the ThemeManager class to add the colorbox.css file to the existing "GRAY_TAB" theme. Of course you can replace "GRAY_TAB" with any other theme that you have already registered.

Please refer to this article for more information about custom themes in Siebel Open UI.

This concludes part 1 of this article. Please click here to go to part 2.

have a nice day

@lex