Skip to content

Plugin Events Reference

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

Plugin Events

You can add Dynamic Actions to respond to various events from the map.

NOTE: make sure to set Fire on Initialization set to No on the Action for your dynamic actions; otherwise you will get javascript errors like "Cannot read property 'lat' of undefined TypeError: Cannot read property 'lat' of undefined".

addressFound

This fires if the user enters an address, or clicks the map, and a geocode result is found. The event provides the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the address location
  • this.data.lng = the Longitude of the address location
  • this.data.result = the GeocoderResult - this will be an object comprising the following attributes, among others:
    • address_components - an array of GeocoderAddressComponent, each consisting of an array of types (usually the first one is the most useful, e.g. "street_number"), a short_name and a long_name. See below for more details.
    • formatted_address - the formatted address string

this.data.result.address_components

The following javascript could be put in a dynamic action which would search for certain desired components from the address and put them in items on the page:

var ac = this.data.result.address_components;

for (i=0; i<ac.length; i++) {

  switch (ac[i].types[0]) {
  case "street_number" :
    $s("P1_STREET_NUMBER", ac[i].short_name);
    break;
  case "route" :
    $s("P1_STREET_NAME", ac[i].short_name);
    break;
  case "locality" :
    $s("P1_LOCALITY", ac[i].short_name);
    break;
  case "administrative_area_level_1" :
    $s("P1_STATE", ac[i].short_name);
    $s("P1_STATE_NAME", ac[i].long_name);
    break;
  case "country" :
    $s("P1_COUNTRY", ac[i].short_name);
    $s("P1_COUNTRY_NAME", ac[i].long_name);
    break;
  case "postal_code" :
    $s("P1_POSTCODE", ac[i].short_name);
    break;
  }

}

The various values that may be found in types may be found here.

addFeature / removeFeature

Only applicable if the Drawing Library is enabled (by setting Drawing Mode). This fires when the user adds or removes a feature. The event has the following attributes accessible via Javascript:

batchLoaded

This fires after each intermediate batch of results has been loaded. Only occurs if the Rows Per Batch attribute is set. The event provides the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.countPins = number of pins retrieved by the query so far
  • this.data.southwest = south-west bound {lat, lng} of the pins retrieved by the query so far
  • this.data.northeast = north-east bound {lat, lng} of the pins retrieved by the query so far

directions

This fires if directions are shown. The event provides the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.distance = total estimated distance, in metres
  • this.data.duration = total estimated travel time, in seconds
  • this.data.legs = number of legs (hops) in the journey
  • this.data.directions = the google.maps.DirectionsResult with all the details of the route [added in v1.2]

geolocate

This fires if the geolocate option is on and the user's current location was able to be determined. The event provides the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the approximate Latitude of the user's current location
  • this.data.lng = the approximate Longitude of the user's current location

loadedGeoJson

Only applicable if the Option: Drag & Drop GeoJSON is set. This fires after a GeoJSON document (whether a file or a JSON fragment) is dropped onto the map and successfully loaded. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.geoJson = the GeoJSON document as a parsed JSON object
  • this.data.features = array of google.maps.Data.Features
  • this.data.filename = the name of the file (if available) [added in v1.5]

mapBoundsChanged

Added in Release 1.5. Fires if the bounds (lat,lng points of the northwest, southeast, etc.) of the visible map are changed (e.g. in response to the user panning or zooming the map). The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapCenterChanged

Added in Release 1.5. Fires if the center (lat,lng) of the visible map is changed (e.g. in response to the user panning the map). The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapClick

This fires when the user clicks in the free area of the map. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the user clicked
  • this.data.lng = the Longitude of the point where the user clicked

mapContextMenu

Added in Release 1.5. Fires when the user invokes the context menu (e.g. using the right mouse button) in the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the user clicked
  • this.data.lng = the Longitude of the point where the user clicked

mapDoubleClick

Added in Release 1.5. Fires when the user double-clicks in the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the user clicked
  • this.data.lng = the Longitude of the point where the user clicked

mapDrag

Added in Release 1.5. Fires repeatedly while the user drags the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the mouse cursor was positioned
  • this.data.lng = the Longitude of the point where the mouse cursor was positioned

mapDragStart / mapDragEnd

Added in Release 1.5. Fires when the user starts or stops dragging the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the mouse cursor was positioned
  • this.data.lng = the Longitude of the point where the mouse cursor was positioned

mapHeadingChanged

Added in Release 1.5. Fires if the map heading is changed. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapIdle

Added in Release 1.5. Fires when the map becomes idle after panning or zooming. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapLoaded

This fires after the map has been initialised and the data first loaded. It does not fire, however, if the plugin does not have a data source (i.e. a query). The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.countPins = number of pins retrieved by the query [added in v1.1]
  • this.data.southwest = south-west bound {lat, lng} of the pins retrieved by the query [added in v1.1]
  • this.data.northeast = north-east bound {lat, lng} of the pins retrieved by the query [added in v1.1]

To have some JavaScript code run after the map is loaded but prior to the data being retrieved, use the Initialization JavaScript Code attribute.

mapMouseMove

Added in Release 1.5. This fires when the user moves the mouse over the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the mouse cursor was positioned
  • this.data.lng = the Longitude of the point where the mouse cursor was positioned

mapMouseOver / mapMouseOut

Added in Release 1.5. This fires when the user's mouse enters or exits the map. Only fires if the Detailed Mouse Events option is enabled. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.lat = the Latitude of the point where the mouse cursor was positioned
  • this.data.lng = the Longitude of the point where the mouse cursor was positioned

mapProjectionChanged

Added in Release 1.5. Fires when the map projection is changed. The event has the following attributes accessible via Javascript:

Tip: call $("#map_mymap").reportmap("instance").map.getProjection() to get the Projection object.

mapRefreshed

This event is identical to mapLoaded except that it does not fire on the initial page load, but fires whenever the region is subsequently refreshed again. It does not fire if the plugin does not have a data source (i.e. a query). The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.countPins = number of pins retrieved by the query [added in v1.1]
  • this.data.southwest = south-west bound {lat, lng} of the pins retrieved by the query [added in v1.1]
  • this.data.northeast = north-east bound {lat, lng} of the pins retrieved by the query [added in v1.1]

mapTilesLoaded

Added in Release 1.5. Fires when the visible map tiles have finished loading. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapTiltChanged

Added in Release 1.5. Fires when the map tilt is changed. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapTypeChanged

Added in Release 1.5. Fires when the map type (e.g. roadmap, satellite, etc.) is changed. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

mapZoomChanged

Added in Release 1.5. Fires when the map zoom is changed. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.center = the {lat, lng} of the center of the visible map
  • this.data.southwest = the {lat, lng} of the south-west bound of the visible map
  • this.data.northeast = the {lat, lng} of the north-east bound of the visible map
  • this.data.zoom = the zoom level (0..23)
  • this.data.heading = the heading (compass heading of aerial imagery, degrees clockwise from North)
  • this.data.tilt = the tilt (0 or 45)
  • this.data.mapType = the map type (roadmap, satellite, hybrid or terrain)

markerAdded

This fires after the map data is loaded or refreshed, for each new pin that has been added to the map. If the pin was previously already shown on the map (based on record ID), this event does not fire for that pin. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.id = the value of the id column from the SQL Query
  • this.data.name = the value of the name column from the SQL Query
  • this.data.lat = the Latitude of the marker location
  • this.data.lng = the Longitude of the marker location
  • this.data.attr01..this.data.attr10 = additional flex fields from the SQL query, if provided
  • this.data.marker = the google.maps.Marker object [added in v1.1]

markerClick

This fires when the user clicks on one of the report markers that were shown on the map. Works for all the pin-type visualisations. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.id = the value of the id column from the SQL Query
  • this.data.name = the value of the name column from the SQL Query
  • this.data.lat = the Latitude of the marker location
  • this.data.lng = the Longitude of the marker location
  • this.data.attr01..this.data.attr10 = additional flex fields from the SQL query, if provided
  • this.data.marker = the google.maps.Marker object [added in v1.1]

NOTE: if the Draggable option is set, the lat/lng will be the marker's current location, not necessarily its original location.

NOTE: for the Info Layer visualisation, the event will fire if the user clicks within the extent of the HTML content rendered.

markerDrag

Only applicable if the Draggable option is switched on. This fires after the user drags one of the report markers to another location on the amp. The event has the following attributes accessible via Javascript:

  • this.data.map = the google.maps.Map object
  • this.data.id = the value of the id column from the SQL Query
  • this.data.name = the value of the name column from the SQL Query
  • this.data.lat = the Latitude of the new marker location
  • this.data.lng = the Longitude of the new marker location
  • this.data.attr01..this.data.attr10 = additional flex fields from the SQL query, if provided
  • this.data.marker = the google.maps.Marker object [added in v1.1]

mouseoverFeature / mouseoutFeature

This fires when the user moves the mouse over or out from a feature (i.e. one loaded via geoJson). The event has the following attributes accessible via JavaScript:

You can access any properties associated with the feature via the getProperty function, e.g. this.data.feature.getProperty('name'). Properties can also be set using setProperty.

selectFeature / unselectFeature

This fires when the user selects or unselects a feature (i.e. one loaded via geoJson). (v1.2: only fires if the Drawing Library is enabled (by setting Drawing Mode)). The event has the following attributes accessible via Javascript:

You can access any properties associated with the feature via the getProperty function, e.g. this.data.feature.getProperty('name'). Properties can also be set using setProperty.

setGeometry

This fires when the user changes the geometry of a feature (i.e. drags it to a new location). Only applicable if the Drawing Library is enabled (by setting Drawing Mode). The event has the following attributes accessible via Javascript:

spiderfy / unspiderfy

Applicable if the Visualisation is set to Spiderfier. These fire when the spiderfier "spiderfies" or "unspiderfies" one or more pins. For example, if a cluster of pins are very close together, and the user clicks on one of them, the spiderfier spreads the pins out in a circle or spiral, and then the "spiderfy" event fires. If the user then clicks on some other unrelated pin, or zooms in or out of the map, the spiderifier restores the original position of the pins, and the "unspiderfy" event fires. These events have the following attributes accessible via Javascript:

Clone this wiki locally