Skip to content

Plugin API Reference

Jump to bottom
Jeffrey Kemp edited this page Jan 23, 2021 · 39 revisions

To create custom interactions with a map on your page you have three options:

  1. Create dynamic actions using the JK64 Report Google Map R1 Action plugin or the JK64 Report Google Map R1 Directions plugin. This is usually the easiest method, although not all API calls listed on this page are supported.

  2. Call any of the plugin API methods listed below. This may be more convenient if you are writing a lot of custom javascript.

  3. Write your own Google Maps API calls against the map object (refer to google.maps.Map, below). This gives maximum customisability as it gives access to the full range of features provided by the Google Maps Javascript API.

API Reference

Using the API

It is recommended that you set the Static ID attribute on your reportmap region. This makes it easy to refer to the correct instance of the reportmap object. If your Static ID is mymap, the jQuery plugin ID will be map_mymap. This ID is used in the examples below, you will need to replace this with your own.

Most methods are invoked via the jQuery plugin, e.g.

$("#map_mymap").reportmap("...method to call here...");

addOverlay

Added in Release 1.5. Add an overlay (e.g. a map image or an info box containing HTML) on top the map. The overlay may be a staticly sized info region positioned at a particular lat,lng coordinate, or it may be scaled over a set of lat,lng bounds (e.g. to show an alternative ground map for a particular area).

Takes two parameters:

  1. Content to render (HTML)

  2. Overlay options - a Javascript object for either a static region or a bounds region: a. Static region - not scaled with map zoom:

    • pos : position the object at this point
    • horizontalAlign : alignment relative to pos - left, center (default), or right
    • verticalAlign : alignment relative to pos - top, middle (default), or bottom
    • horizontalOffset : pixel offset (x) (default: no offset)
    • verticalOffset : pixel offset (y) (default: no offset)

    b. Bounds region - scaled according to map zoom:

    • bounds : null, // scale the object to match this range of lat,long coordinates (e.g. to show a map image on top of the map)

    Both types:

    • minZoom : hide if zoomed out past this level (default: none)
    • maxZoom : hide if zoomed in past this level (default: none)
    • onClickHandler : function to call if overlay clicked (null to make not clickable)

Example 1:

const content = '<div style="background:white">You are Here</div>';
$("#map_mymap").reportmap("addOverlay", content, {
    pos           : { lat: -31.957, lng: 115.857 },
    verticalAlign : "top"
});

Example 2:

const bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(-31.960837, 115.852273),
    new google.maps.LatLng(-31.956112, 115.860740) 
);
const img = '<img src="path-to-source/image.jpg" style="width:100%; height:100%; position:absolute;">`;
$("#map_mymap").reportmap("addOverlay", img, { bounds: bounds });

click

Search the report for a pin by its id value (as returned by the SQL query), and "click" it.

Example:

$("#map_mymap").reportmap("click", "12345");

deleteAllFeatures

Remove all GeoJSON features from the map.

Example:

$("#map_mymap").reportmap("deleteAllFeatures");

deleteSelectedFeatures

Remove any selected GeoJSON features from the map. The user can select one or more features by first clicking on them.

Example:

$("#map_mymap").reportmap("deleteSelectedFeatures");

fitBounds

Pan/Zoom the map to show the given bounds.

Example:

$("#map_mymap").reportmap("fitBounds", {north:-10, south:-44, west:110, east:155} );

geolocate

Search for the user device's location using navigator.geolocation.getCurrentPosition, if possible (and allowed by the user).

PRE-REQUISITE: to use Geocoding you must enable the Geocoding API on your Google Cloud Platform project. Read "Getting started" at https://developers.google.com/maps/documentation/javascript/geocoding to enable the Geocoding API.

Example:

$("#map_mymap").reportmap("geolocate");

getAddressByPos

Search for the closest address to the given lat / long position using google.maps.Geocoder and raise addressfound trigger if successful.

PRE-REQUISITE: to use Geocoding you must enable the Geocoding API on your Google Cloud Platform project. Read "Getting started" at https://developers.google.com/maps/documentation/javascript/geocoding to enable the Geocoding API.

Example:

$("#map_mymap").reportmap("getAddressByPos", -24.8848, 113.6566);

gotoAddress

Search the map for an address using google.maps.Geocoder; if found, put a pin at that location and raise addressfound trigger.

PRE-REQUISITE: to use Geocoding you must enable the Geocoding API on your Google Cloud Platform project. Read "Getting started" at https://developers.google.com/maps/documentation/javascript/geocoding to enable the Geocoding API.

Example:

$("#map_mymap").reportmap("gotoAddress", "5 The Esplanade, Perth");

gotoPos

Place or move the user's pin to the given location.

Example:

$("#map_mymap").reportmap("gotoPos", -24.8848, 113.6566);

gotoPosByString

Parse a string as a lat,long pair and put a pin at that location.

Example:

$("#map_mymap").reportmap("gotoPosByString", "-24.8848,113.6566");

hideMessage

Hide the Warning/Error message.

Example:

$("#map_mymap").reportmap("hideMessage");

loadGeoJsonString

Load a set of features specified in a GeoJSON object.

Example:

$("#map_mymap").reportmap("loadGeoJsonString",
  '{
      "type": "Feature",
      "geometry": {
          "type": "Point",
          "coordinates": [125.6, 10.1]
      }
   }');

panToByString

Pan to the given location determined by a lat,long pair or by a street address or other location description.

Example:

$("#map_mymap").reportmap("panToByString", "Barcelona, Spain");

showDirections

Show a route from one point to another. Each point may be designated by a lat,long pair, or by a street address or other location description. The default travel mode is "Driving".

The Show Directions plugin calls this method.

Parameters:

  • origin = start location
  • destination = end location
  • travelMode = (optional) - may be 'DRIVING', 'WALKING', 'BICYCLING', or 'TRANSIT' (note: must be uppercase)

PRE-REQUISITE: to use Directions you must enable the Directions API on your Google Cloud Platform project. Read "Getting started" at https://developers.google.com/maps/documentation/javascript/directions to enable the Directions API.

Example:

$("#map_mymap").reportmap("showDirections",
    "-24.8848,113.6566",
    "Exmouth, Western Australia",
    "DRIVING");

showMessage

Show a Warning/Error message. The message is shown in a light yellow box centered left in the viewing window.

Example:

$("#map_mymap").reportmap("showMessage", "Carmen Sandiego not found.");

google.maps.Map instance

The Google Map object created by the plugin can be used directly; this supports the full range of capabilities as documented here.

Examples:

  • Get the map object:

    var m = $("#map_mymap").reportmap("instance").map;

    If you are on APEX 5.1 or earlier, the above syntax may not work as it requires jQuery-UI version 1.11 or later. If you are on an older version, use this syntax instead:

    var m = $("#map_mymap").data("jk64Reportmap").map;

  • Zoom the map to a particular level (0..23):

    var m = $("#map_mymap").reportmap("instance").map;
m.setZoom(13);

  • Pan the map to a particular location:

    var m = $("#map_mymap").reportmap("instance").map;
m.panTo({lat:-24.8848, lng:113.6566});

  • Pan and zoom the map so that it shows the given extent:

    var m = $("#map_mymap").reportmap("instance").map;
m.fitBounds({
  south:-33.9337,
  west: 151.070,
  north:-33.7611,
  east: 151.3385
});

    or

    var m = $("#map_mymap").reportmap("instance").map,
    southwest = {-33.9337, 151.070},
    northeast = {-33.7611, 151.3385};
m.fitBounds(new google.maps.LatLngBounds(southwest,northeast));

  • Set tilt:

    var m = $("#map_mymap").reportmap("instance").map;
m.setTilt(45);

  • Change map type:

    var m = $("#map_mymap").reportmap("instance").map;
m.setMapTypeId("hybrid");
m.setMapTypeId("roadmap");
m.setMapTypeId("satellite");
m.setMapTypeId("terrain");

  • Get the map's current center location:

    var pos = $("#map_mymap").reportmap("instance").map.getCenter();
console.log( pos.lat(), pos.lng() );

  • Get the map's current bounds:

    var b = $("#map_mymap").reportmap("instance").map.getBounds();
console.log( b.getNorthEast().toString() );
console.log( b.getSouthWest().toString() );

  • Export all the features on the map as a GeoJSON file:

    var m = $("#map_mymap").reportmap("instance").map;
m.data.toGeoJson(function(o){
    console.log( JSON.stringify(o) );
});
Clone this wiki locally