Friday May 24, 2013

A sample application using the V2 API

This entry describes a simple Oracle Maps V2 application which displays a predefined vector layer (aka theme) on a tile layer. The vector layer is called 'Customers' and the tile layer is named 'demo_map'.  The vector layer is based on a database table named CUSTOMERS and it's definition (in user_sdo_themes) is as follows:

SQL> select base_table, geometry_column, styling_rules from user_sdo_themes
  2  where name='CUSTOMERS';

BASE_TABLE
----------------------------------------------------------------
GEOMETRY_COLUMN
-------------------------------------------------------------------------------
STYLING_RULES
-------------------------------------------------------------------------------
CUSTOMERS
LOCATION
<?xml version="1.0" standalone="yes"?>
<styling_rules key_column="NAME">
  <hidden_info>
    <field column="NAME" name="Name"/>
    <field column="CITY" name="City"/>
    <field column="SALES" name="Sales"/>
    <field column="ACCOUNT_MGR" name="Account Manager"/>
  </hidden_info>
  <rule>
    <features style="M.SMALL TRIANGLE"> </features>
    <label column="NAME" style="T.RED STREET"> 1 </label>
  </rule>
</styling_rules>

 The above means that the predefined vector layer will select the name, city, sales, account_mgr, and location columns from the customers table and render the location using the marker style named "M.SMALL TRIANGLE" and label the locations (when possible) with the value of the NAME column using the text styles "T.RED STREET".

The end result will look something like the screenshot below.


The source code for the sample application is:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<TITLE>A sample Oracle Maps V2 application</TITLE>
<script language="Javascript" src="/mapviewer/jslib/v2/oraclemapsv2.js"></script>
<script language=javascript>
var customersLayer=null;

$(document).ready(function() {
  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.
  // Note: Change from V1. In V2 initialization and initial display is done just once
  mapview.init();
});

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);
}
</script>
</head>

<body>
<h2>A Sample Oracle Maps V2 Application</h2>
<INPUT TYPE="checkbox" onclick="setLayerVisible(this)" checked/>Show customers
<div id="map" style="width: 600px; height: 500px"></div> 
</body>
</html>

The above code has an html portion and some javscript code which uses the Oracle Maps API.

The html portion consists of a header, a checkbox to determine whether the customers layer is displayed or hidden, and a DIV 600 pixels in width and 500 pixels in height.

The javascript code first loads the oraclemapsv2 library

<script language="Javascript" src="/mapviewer/jslib/v2/oraclemapsv2.js"></script>

 and since oraclemapsv2.js also includes and loads jquery (1.7.2) we can now use the jquery object (or its alias $) and its methods within our code. So we use the ready() method to specify the function, containing our OracleMaps code, to execute when the DOM is ready. The OracleMaps code must do the following:

Create an OM.Map object and associate it with the HTML DIV where the map will be displayed.
Create one or more tile layers (i.e. the background map)
Set a map center and zoom level
Optionally, add one or more interactive vector layers
Optionally, add some map controls and decorations such as a navigation panel and scale bar
Initialize and display the map

The first step is done in the following code snippet:

 

  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
                           });

An OM.Map object needs to know where to display a map and which mapviewer instance will handle its requests. So there are two parameters, the "map" DIV and the mapviewerURL.
The next step is to define the background map, or the tile layers.

 

  // 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);

A tile layer comes from a specified datasource, has a unique name, and is rendered by a specified mapviewer instance. Now we need to specify the initial map center and zoom level.

  // 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);    

The Point constructor takes a X, Y and an SRID. In this case it is 8307 which is the SRID for spatial reference system commonly used for GPS devices.

SQL> select cs_name from cs_srs where srid=8307;
CS_NAME
--------------------------------------------------------------------------------
Longitude / Latitude (WGS 84)

Once that's done we add an interactive vector layer.

 

  // Add a vector(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);

Like a tile layer, a predefined vector layer comes from a specified datasource, has a unique name, and is rendered by a specified mapviewer instance.

Next we add some map decorations and controls and finally initialize and display the map.

  // 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.
  // Note: Change from V1. In V2 initialization and initial display is done just once
  mapview.init();

The last piece is the function which toggles the display of the Customers layer.

 

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);
}
 
  

Tuesday May 07, 2013

Intro to the V2 API

So what is the V2 API? Same as the V1 (oracle maps javascript) API but different :-)

The key differences are:

  •  Client side rendering of themes (or theme-based FOI) using SVG or html5 canvas. Themes are called vector layers in V2. FOI are called Features.

  • A map tile layer is not required in order to display a vector layer (theme). That is, a layer (such as county_population_density) can be displayed just by itself and have specified (fixed) zoom levels without any background tile layer. In other words you can have interactive, zoom-able, thematic maps.
  • A namespace (OM) and a different way of specifying parameters. (This is best explained by examples and will be done below)
  • Support for json files as a data source, aka data packs.

What then are the similarities? Well the same concepts (tile layers, themes, styles, styling rules), architecture, and content organization apply. They both depend on Oracle Spatial for spatial data management and analysis. And while one could define all styles and tile layer definitions dynamically, the ones defined via MapBuilder still work. The table below (from the user guide. Thanks Chuck) lists the correspondence between methods in V1 and V2.

V1 API Class V2 API Class

MVMapView

OM.Map

MVMapTileLayer, MVBingTileLayer, built-in tile layers

OM.layer.TileLayer, OM.layer.BingTileLayer, ElocationTileLayer, NokiaTileLayer, OSMTileLayer

MVCustomMapTileLayer

Custom tile layers are not directly supported in the current release of V2. However, you can use custom tile layers by extending OM.layer.TileLayer and supplying a getTileURL callback function.

MVThemeBasedFOI

OM.layer.VectorLayer

MVFOI

OM.Feature

MVSdoGeometry

OM.geometry and its subclasses

MVEvent

OM.event and its subclasses

MVInfoWindowTab

OM.infowindow.MVInfoWindowTab

Styles (MVStyleColor, MVXMLStyle, MVBucketStyle, MVBarChartStyle, and so on)

OM.style and its subclasses

Tools (MVToolbar, MVDistanceTool, MVCircleTool, and so on)

OM.tool and its subclasses

Decorations and controls (MVNavigationPanel, MVMapDecoration, MVScaleBar, and so on)

OM.control and its subclasses

 The V2 API has the following top-level classes and subpackages, all of which are in the namespace OM:

  • The Map class is the main class of the API.

  • The Feature class represents individual geo features (or FOIs as they were known in V1).

  • The MapContext class a top-level class encapsulating some essential contextual information, such as the current map center point and zoom level. It is typically passed into event listeners.

  • The control package contains all the map controls, such as navigation bar and overview map.

  • The event package contains all the map and layer event classes.

  • The filter package contains all the client-side filters (spatial or relational) for selecting, or subsetting, the displayed vector layer features.

  • The geometry package contains various geometry classes.

  • The layer package contains various tile and vector layer classes. The tile layer classes include access to a few online map services such as Oracle, Nokia, Bing, and OpenStreetMap. The vector layers are interactive feature layers and correspond to the MVThemeBasedFOI and MVFOI classes of V1.

  • The infowindow package contains the customizable information windows and their styles.

  • The style package contains styles applicable to vector data on the client side. It also includes visual effects such as animation, gradients, and drop shadows.

  • The tool package contains various map tools such as for distance measuring, red-lining, and geometry drawing.

  • The universe package contains built-in, or predefined, map universes. A map universe defines the bounding box and set of zoom level definitions for the map content. It is similar to a tile layer configuration in the V1 API.

  • The util package contains various utility classes.

  • The visualfilter package provides an interface for the various visual effects, such as gradients and drop shadows.

OM.Map is the main entry class for all map operations inside the web browser. This and other classes provide interfaces for adding application-specific logic, operations, and interactivity in web mapping applications.

In the next post we'll look at a simple example of using the V2 API.

Friday May 03, 2013

Planned entries for this blog

Over the course of the next few weeks (an entry per week or so) we plan to discuss the new javascript API. After that we'll address Luis Paolini's questions about using mapviewer with database features such as VPD etc.


User Conference info, new features in MapViewer

The Spatial and Graph User Conference will be in DC (Reagan International Center) on May 22nd. The agenda is available at http://www.locationintelligence.net/dc/agenda/.

LJ has two sessions during which he'll talk about some of the new features in MapViewer which include:

  • A new HTML5 Canvas based Javascript API which provides richer interactivity and responsiveness.
  • A web-based spatial data editor. It initially supports 2-d geometry editing (points, lines, polygons, collections) but not planar or network topology. Can be used with Workspace Manager.
  • Access to alternate spatial data sources via GDAL/OGR


About

Official blog for Oracle FMW MapViewer and related products.

Search

Categories
Archives
« May 2013 »
SunMonTueWedThuFriSat
   
1
2
4
5
6
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
25
26
27
28
29
30
31
 
       
Today