4.1 Oracle Maps JavaScript API

The Oracle Maps JavaScript client is a browser-based map visualization engine that works on top of the map tile server and that uses HTML5 technology.

It implements the following functions:

• Fetching map tiles from the map tile server and displaying them as a map tile layer in the web browser.

• Controlling user interaction, such as dragging for map navigation, clicking features, drawing rectangles, and redlining.

  Drawing a rectangle refers to the application user creating a rectangle by clicking and holding the mouse button at one corner of the rectangle, dragging the mouse to the diagonally opposite corner, and releasing the mouse button.

  Redlining refers to the application user creating a polygon or polyline by clicking the mouse button and then moving the mouse and clicking multiple times, with each click extending the redline by a straight line. (Redline drawings are often rendered in red, although you can specify a line style that uses any color.)

To access these functions, use the JavaScript API, which consists of several JavaScript classes. For detailed information about all classes in the Oracle Maps JavaScript API, see the Javadoc-style reference documentation, which is available at:

http://<host>:<port>/mapviewer/jslib/<version>/apidoc/index.html

• About the Oracle Maps JavaScript API
  

4.1.1 About the Oracle Maps JavaScript API

The Oracle Maps JavaScript API takes advantage of the capabilities of modern browsers and HTML5. Some of its features include:

• Built-in support of various third party map tile services, such as maps.oracle.com, Nokia Maps, OpenStreet Maps, and other mapping service providers

• Rich client side rendering of geospatial data with on-the-fly application of rendering styles and effects such as gradients, animation, and drop-shadows

• Autoclustering of large number of points and client side heat map generation

• Client side feature filtering based on attribute values as well as spatial predicates (query windows)

• A rich set of built-in map controls and tools, including a customizable navigation bar and information windows, configurable layer control, and red-lining and distance measurement tools

Existing server-side predefined styles and themes will work with the API. For example, the following code snippet creates an interactive vector layer based on a predefined theme mvdemo.customers, which has an associated predefined style:

var baseURL  = "http://"+document.location.host+"/mapviewer";
var layer = new OM.layer.VectorLayer("layer1",  
 {
     def:{
                type:OM.layer.VectorLayer.TYPE_PREDEFINED, 
                dataSource:"mvdemo", 
                theme:"customers", 
                url: baseURL
            }
  });

The 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.

• 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, and OpenStreetMap. The vector layers are interactive feature layers.

• 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.

• 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. The application logic and operations can include the following:

• Create a map client instance and associate it with the map container DIV object created in the web page.

• Configure map parameters such as map center and map zoom level.

• Optionally, create and manipulate map tile layers. A map tile layer is not required. An application can have only interactive vector layers using a custom Universe that programmatically defines the zoom levels and scales.

• Create and manipulate vector layers.

• Display an information window on the map.

• Create fixed map decorations, such as a map title, a copyright note, and map controls.

• Access built-in utilities such as a navigation panel, rectangle or circle tool, scale bar, and overview map panel.

• Use event listeners to customize event handling and thus map interactions.

Other notes and considerations on using the Oracle Maps API:

• The "FOI server" in a previous version of the API is now a data server that streams the vector geometries and attributes for features to the client for local rendering. Therefore, the "FOI layers" in a previous version are now called vector layers.

• A background map tile layer is not required in order to display interactive vector layers. For example, an application can display a thematic map of states (such as color-filled by population quintile) with no background tile layer.

• The API depends on and includes JQuery and JQueryUI. So, oraclemapsv2.js includes jquery-1.7.2.min.js and jquery-ui-1.8.16.min.js. If your application also uses JQuery and JQueryUI and includes them already, then use the file oraclemapsv2_core.js in the <script> tag instead to load the Oracle Maps library. That is, use the following:

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

  instead of:

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

For information about developing applications using the API, see Developing Oracle Maps Applications and the Oracle-supplied tutorials and demos.