Developing Oracle Maps Applications

This topic describes how to develop Oracle Maps applications.

If the underlying base map and layers are managed in an Oracle AI Database, each map tile layer displayed in the client application must have a corresponding database metadata entry in the USER_SDO_CACHED_MAPS metadata view (described in xxx_SDO_CACHED_MAPS Views) . Similarly, if an interactive layer is based on database content, it must have a metadata entry in the USER_SDO_THEMES view (described in Map Visualization Component Metadata Views, especially xxx_SDO_THEMES Views). These tile and interactive layers, and the styles and styling rules for them, can be defined using the Map Builder tool (described in Oracle Map Builder Tool).

To develop Oracle Maps applications using the API, follow these basic steps:

Import the oraclemapsv2.js library.

The API is provided in a single JavaScript library packaged as part of the map visualization component EAR archive.

After the map visualization component is deployed and started, load the library through a <script> tag, for example:

<script  type="text/javascript" url="http://localhost:8080/mapviewer/jslib/v2/oraclemapsv2.js"/>

Note:

If you need a specific jQuery version other than the one packaged in oraclemapsv2.js (shown in the preceding example), then you can add your preferred jQuery first, followed by a list of libraries. For example:

<script src="your_preferred_jQuery_library_listed_here_first.js "></script>

<script src="v2/jquery/jquery.hammer-full.min.js"></script>

<script src="v2/jquery/jquery.i18n.properties-min-1.0.9.js"></script>

<script src="v2/jquery/jquery.mousewheel.min.js"></script>

<script src="v2/rtree/rtree-min.js"></script>

<script src="v2/fortknox-libs/fortknox-canvas.js"></script>

<script src="v2/oraclemapsv2_core.js"></script>

Create a <DIV> tag in the HTML page, which will contain the interactive map.
Create a client-side map instance that will handle all map display functions.

The class is named OM.Map and is the main entry point of the API.
Set up a map universe (unless you also do the optional next step).

A map universe basically defines the overall map extent, the number of zoom levels, and optionally the resolution (in map units per pixel) at each zoom level. Note that a predefined tile layer is not necessary in order to display interactive vector layers or themes. For example, an interactive thematic map of sales by region does not need to have a background map, or tile layer.
(Optional) Add a tile layer that serves as the background map.

The tile layer can be from the database, such as mvdemo.demo_map, or from a supported service, such as Nokia Maps. Adding a tile layer also implicitly defines a map universe, and therefore the preceding step (setting up a map universe) is not necessary in this case.
Add one or more interactive vector layers.

OM.VectorLayer uses HTML5 (Canvas or SVG) technology to render all the data in the browser. So, unless specified otherwise, all vector layer content is loaded once and there are no subsequent database queries, or data fetching, on map zoom or pan operations.
Add one or more map controls, tools, and other application-specific UI controls so that users can set the displayed layers, styling, and visual effects.

If you need to prevent themes from being streamed by default, you must protect them is by adding authentication, that is, by adding a security constraint in the map visualization component web.xml file and by configuring the mds.xml file to authorize access to various themes. For information, see Configuring and Securing the Map Data Server for the HTML5 API.

For detailed instructions and related information about using the API, see the Oracle-supplied tutorials and demos.

Creating the Client Application with the API

Creating the Client Application with the API

Oracle Maps applications run inside web browsers and require only HTML5 (Canvas) support and JavaScript enabled. No additional plugins are required.

The source for an Oracle Maps application is typically packaged in an HTML page, which consists of the following parts:

A <script> element that loads the Oracle Maps client library into the browser’s JavaScript engine. For example:
```
<script src="/mapviewer/jslib/v2/oraclemapsv2.js"></script>
```
An HTML <div> element that will contain the map. For example:
```
<div id="map" style="width: 600px; height: 500px"></div>
```

JavaScript code that creates the map client instance and sets the initial map content (tile and vector layer), the initial center and zoom, and map controls. This code should be packaged inside a function which is executed when the HTML page is loaded or ready. The function is specified in the onload attribute of the <body> element of the HTML page. For example:

function on_load_mapview()
{
  var baseURL  = "http://"+document.location.host+"/mapviewer";
  // Create an OM.Map instance to display the map
  var mapview = new OM.Map(document.getElementById("map"),
                           {
                             mapviewerURL:baseURL
                           });
  // Add a map tile layer as background.
  var tileLayer = new OM.layer.TileLayer(
        "baseMap",
        {
            dataSource:"mvdemo",
            tileLayer:"demo_map",
            tileServerURL:baseURL+"/mcserver"
        });
  mapview.addLayer(tileLayer);
  // Set the initial map center and zoom level
  var mapCenterLon = -122.45;
  var mapCenterLat = 37.7706;
  var mapZoom = 4;
  var mpoint = new OM.geometry.Point(mapCenterLon,mapCenterLat,8307);
  mapview.setMapCenter(mpoint);
  mapview.setMapZoomLevel(mapZoom);
  // Add a theme-based FOI layer to display customers on the map
  customersLayer = new OM.layer.VectorLayer("customers",
        {
            def:
                {
                type:OM.layer.VectorLayer.TYPE_PREDEFINED,
                dataSource:"mvdemo", theme:"customers",
                url: baseURL,
                loadOnDemand: false
                }
        });
  mapview.addLayer(customersLayer);
  // Add a navigation panel on the right side of the map
  var navigationPanelBar = new OM.control.NavigationPanelBar();
  navigationPanelBar.setStyle(
{backgroundColor:"#FFFFFF",buttonColor:"#008000",size:12});
  mapview.addMapDecoration(navigationPanelBar);
  // Add a scale bar
  var mapScaleBar = new OM.control.ScaleBar();
  mapview.addMapDecoration(mapScaleBar);
  // Display the map.
  // The initialization and display is done just once.
  mapview.init();
}

Additional HTML elements and JavaScript code that implement other application-specific user interface and control logic. For example, the HTML <input> element and JavaScript function setLayerVisible together implement a layer visibility control. The setLayerVisible function is coded as follows:
```
function setLayerVisible(checkBox)
{
  // Show the customers vector layer if the check box is checked and
  // hide it otherwise.
  if(checkBox.checked)
    customersLayer.setVisible(true) ;
  else
    customersLayer.setVisible(false);
}
```
The function is specified in the onclick attribute of the <input> element defining the checkbox. In the following example, the function is executed whenever the user clicks on the Show Customers check box:
```
<INPUT TYPE="checkbox" onclick="setLayerVisible(this)" checked/>Show Customers
```