16 October 2014

How to make use of maps in Forms 11g?

Author: Cătălin Bulancea

This blog posting is about how easy it is to integrate your existing or new Oracle Forms 11g applications with map visualization and navigation capabilities. Oracle FMW MapViewer is the key to that since it provides Oracle Maps with JavaScript API.

For all the Oracle Forms users out there…have you wondered lately what are the key features of Oracle Forms 11g?

Of course, you can read it all from here or here. With the increased utilization of Java, web technologies (HTML5) and integration strategies, Oracle Forms 11g tries to keep up with the New. And I feel it succeeds in doing just that!

What I would like to focus on this topic is one of the most important features: Oracle Forms 11g is JavaScript enabled! This new functionality makes it possible to execute JavaScript in the page in which the Forms applet is embedded.

JavaScript can be used to integrate Forms with any application that provides a JavaScript API, or simply with custom HTML/ADF pages that embed JavaScript functionality.

While integrating Forms with HTML controls is nice, the integration of Oracle Forms with a map displays a spectacular result! It’s time for the main character in this play to step on the stage: Oracle Fusion Middleware MapViewer! See more here.

Oracle FMW MapViewer currently provides 2 JavaScript APIs (the newer one supports HTML 5) for incorporating highly interactive maps and spatial analysis. The integration with Oracle Forms is done via one of these JavaScript APIs.

What would an integrated application look like? Let’s suppose you’re a company with multiple offices that provide different services based on the location and office type. Displaying that info in an HTML table doesn’t look very appealing to the customers, while they get lost in the tons of information.

Why not displaying all the office locations on a map? When a customer clicks on a location, an information window provides all necessary information at the first glance. May be also a thumbnail of an image representing the office, as well as a link to a web resource giving even more information.

How is this done?

First, make sure you have an Oracle Database 11g (11.2.0.3 minimum) with Oracle Spatial or at least Oracle Multimedia (which includes Oracle Locator) installed.

Then, you need to have Oracle Forms 11g and install Oracle FMW MapViewer on top of it. Download MapViewer from here and then install the Mapviewer.ear according to the documentation.

Oracle FMW MapViewer comes with a demo application called MVDEMO (please note that this web resource is not assured to be available 24x7) which is a great way to get you started! After importing the MVDEMO sample data into your database, deploy MVDEMO.war onto a WebLogic Server and configure the data source in the MapViewer Administration Console:

<map_data_source name="mvdemo"
            jdbc_host="&ltYOUR DB HOST>"
            jdbc_sid ="&ltDB SID>"
            jdbc_port="&ltDB PORT>"
            jdbc_user="mvdemo"
            jdbc_password="!mvdemo" 
            jdbc_mode="thin"
            number_of_mappers="3"
            allow_jdbc_theme_based_foi="false"
            editable="false"
/>
The samples page will be accessible at this URL: http://formshost:formsport/mvdemo

In Oracle Forms formsweb.cfg configuration file, you add a section as below:

[formsmapviewer]
baseHTMLjpi=jsmap.html
userid=dbuser/dbpass@host:port/SID
form=formsmapviewer.fmx
width=320
height=763
# Config for javascript integration
applet_name=formsmapviewer_applet
enableJavascriptEvent=true
JavaScriptBlocksHeartBeat=true
splashScreen=no
guiMode=3
lookAndFeel=Oracle
colorScheme=blue
Calling your forms application using above section will assure that JavaScript is used. Notice the baseHTMLjpi parameter which takes a custom file built on the template basejpi.htm, called jsmap.html. This file will contain our Forms application applet embedded and all the JavaScript code.

This is how we display the map, centering it at Oracle Munich office:

function showMap() 
{ 
  mapview = new MVMapView(document.getElementById("map"), baseURL);
  mapview.addMapTileLayer(osmBasemap);

  //Oracle Munich office
  var mpoint = MVSdoGeometry.createPoint(11.56, 48.13, 8307);
  mapview.setCenterAndZoomLevel(mpoint,7);

  mapview.addNavigationPanel() ;    
  mapview.display();

  mapview.addCopyRightNote("&2014 Powered by Oracle ©2010 GfK GeoMarketing");
  mapview.addNavigationPanel("EAST");
  mapview.addScaleBar();
}

If you are asking yourselves where does osmBasemap come from, this is a custom map tile layer based on the tile configuration. For more details, check out Jayant's post. The baseURL is the URL where Mapviewer was installed: http://host:port/mapviewer

The map itself is a DIV element in HTML and it can be referenced by its id in JavaScript:

<div id="map" style="left:0px; top:0px; width:1250; height:763"></div>
Last but not least, you need to develop/modify your Forms application in order to "speak" JavaScript. For example, we have a ZoomIn button in Forms that will zoom in the map. The code used to do that is found in the WHEN-BUTTON-PRESSED trigger and it's easy-peasy:
web.javascript_eval_expression('zoomIn();');
web.javascript_eval_expression is a procedure which takes an expression as the argument. This legal JavaScript expression is interpreted in the Web page in which the Forms applet is embedded and in our case is the JavaScript function zoomIn().

Another example is creating a Feature of Interest (FOI) on the map with the longitude and latitude coordinates given inside the Forms application:

web.javascript_eval_expression('createFOI('||:CONTROL.LONG||','||:CONTROL.LAT||', 8307);');
For more information on Oracle Forms and JavaScript integration, read Oracle© Fusion Middleware Forms Services Deployment Guide here and Metalink Note: "A Guide to Integrating JavaScript with Forms&quot (Doc ID 853911.1);.

The Forms application eventually looks like this:

http://formshost:formsport/forms/frmservlet?config=formsmapviewer


Application features used for this demo:
  • Zoom in, zoom out from both map and the Forms application
  • Pan up, down, left, right from both map (navigation panel) and the Forms application
  • Overview map on the right bottom corner with the possibility to move the map
  • Scale bar on the left bottom corner of the map
  • Copyright note on the right bottom corner
  • Features of Interest:
    • When hitting "Create FOI" button an image is created on the map at the longitude and latitude coordinates specified as parameters.
      When clicking the image an Information Window with Oracle is opened and you can navigate to the webpage
    • Hit Remove FOI to delete the feature of interest (needs the id of the FOI)
    • Alternatively, you can create other FOIs by specifying different coordinates
  • Custom themes: (In Germany appear when selecting the checkboxes "On mouse over" the airports or highways, you'll see their name.)
    • Airports and
    • Highways

Feel free to try it out and enhance your Forms application with a nice map.

Any feedback is highly appreciated.

Thanks, Cătălin