Skip to content

Plugin Attributes Reference

Jump to bottom
Jeffrey Kemp edited this page Feb 9, 2021 · 95 revisions

Map Region Plugin Attributes

Application-level Attributes

Region Attributes

Region Plugin Attributes

Other Attributes

Appendix

Application-level Attributes

Set these in Shared Components / Component Settings. These attributes are applied to all instances of the plugin in the application.

Google API Key

Required. If you don't set this, you will get an error popup and a "NoApiKeys" error in the console log. Refer: https://developers.google.com/maps/documentation/javascript/get-api-key#get-an-api-key

No Address Results message

Optional. Set this to override the default message to display if an address search returns no results.

Directions Not Found message

Optional. Set this to override the default message to display if directions are requested for locations not found.

Directions Zero Results message

Optional. Set this to override the default message to display if directions is unable to find a route between any of the origin, destination or intervening waypoints.

Min. Zoom

Minimum Zoom Level - must be 0 to 23. Set to 0 to allow zooming out to entire world map.

Max. Zoom

Maximum Zoom Level - 0 to 23. Set to blank to allow zooming in to show maximum detail.

Maximum Records

Required. Maximum number of records to fetch from the SQL Query. Note that datasets that are very large (e.g. 10,000+) may perform poorly on the client's machine. The Heatmap option is leaner and can support larger datasets.

Unit System

Added in Release 1.5. Required. "Metric" (default) or "Imperial". Unit system to use for the Directions service. This affects how Directions are shown (e.g. kilometres vs. miles) and how the Directions event reports the total Distance (meters vs. miles).

Plugin URL Path

Added in Release 1.5. Optional. Normally, this may be left blank (i.e. auto-detect). Set this to override the automatic detection of the window origin+path for downloading plugin image icons. Don't include a trailing slash (/). The plugin will append the plugin path prefix and the file name at run time.

Region Attributes

Set these on the plugin Region.

Source

  • Source - (none)

    If you just want a map without any data.

  • Source - Location

    Set to Local Database (e.g. to use a SQL Query).

  • Source - Type

    If Local Database, set Type to Table / View, SQL Query or PL/SQL Function Body returning SQL Query.

Table / View

The columns expected by the selected Visualisation must be named correctly. Refer to SQL Query examples for more details.

SQL Query

The column order and data types must be exactly as the plugin expects. Refer to SQL Query examples for more details.

Page Items to Submit

Set to any page items if the SQL Query is dependent on any.

Static ID

If left blank, the internal region ID will be used to generate the plugin. It is recommended to set this to a predictable value if you wish to interact with the plugin using custom JavaScript.

Messages: When No Data Found

Message to show if the query returns no rows. If blank, APEX supplies a default message. To suppress the message, set the plugin option "Suppress No Data Found message".

Region Plugin Attributes

Set these on the plugin region Attributes.

Min. Map Height

Desired height (in pixels) of the map region. Note: the width will adjust according to the available area of the containing window.

Visualisation

Required. This controls how the data is presented on the map. Set to one of the following options:

  • Pins (default)

    Show a pin for every data point. The pin may optionally use an alternative icon, or show a single-character label. Each pin can also have an information window showing text (most HTML allowed) when the user selects the pin.

  • Info Layer

    Added in Release 1.5. Show the Info (as HTML rendered within a div) directly on the map instead of pins. The size of the div will depend on the content you provide. The content may include text, HTML formatting, icons, and images.

  • Marker Clustering

    Show a pin for every data point. Cluster pins where many pins are very close together.

  • Spiderfier [v1.2]

    Show a pin for every data point. If the user clicks on a group of pins that are close to each other or overlapping, the spiderfier shifts the pins out in a spiral with lines pointing to where they were.

  • Heatmap

    Show the data as a heat map. Suitable for larger volume of data points. Note: a different query structure is required (i.e. no pin labels or icons are used).

  • Directions

    Show a route using the data points from the query. Directions can be shown for Driving, Walking, Bicycling or Public Transport. A pin will also be shown at each point.

    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.

Zoom Level on Click

Zoom the map to this level (0..23) when the user clicks on a map marker, adds a new marker, or the geolocate action finds the device location. Set to blank to not zoom on any of these events.

See also: Pan on click below.

Option: Pan on click

On by default. If set, when the user clicks on a pin the map will pan so the pin will be visible. Set off to stop this behaviour. NOTE: if you switch this off, you will almost certainly want to clear out Zoom Level on Click - otherwise when the user clicks a pin the map will zoom but not pan.

Option: Draggable pins

Allow user to move the pins around on the map. When a pin is moved, the markerDrag event is triggered (refer to Plugin Events Reference).

NOTE: The Draggable pins option does not work with the Directions visualisation.

Option: Pan Allowed

On by default. Set this to allow the user to pan (move) the map view to different points interactively. To fix the map to the starting location, switch this attribute off.

Option: Zoom Allowed

On by default. Set this to allow the user to zoom the map interactively. To fix the map to the initial zoom level, switch this attribute off.

Option: Drag & Drop GeoJSON

Allow user to drag and drop a GeoJSON file onto the map. The features in the GeoJSON will be rendered into a data layer on the map.

If you also enable Drawing Mode, the user will also be able to edit these features, and add and remove features.

You can get the resulting set of features as a new GeoJSON document using code like this:

var map = $("#map_mymap").reportmap("instance").map;
map.data.toGeoJson(function(o){
    $s("P1_GEOJSON", JSON.stringify(o));
});

Option: Disable Auto Fit Bounds

By default, whenever the map data is refreshed, the map will be automatically panned/zoomed to fit the bounds of all the pins. Set this option to stop the map from automatically fitting the bounds.

Option: Show Spinner

Show APEX "waiting" spinner while data is loading or refreshing.

Option: Suppress No Data Found message

Added in Release 1.5. If set, when the query returns no rows, no message will be shown. The default behaviour is to show a "No Data Found" popup message.

Option: Detailed Mouse Events

Added in Release 1.5. Add a listener for detailed mouse events (contextmenu, drag, dragend, dragstart, mouse over, mouse move, mouse out, double click). Required if you need a dynamic action to respond to any of these events. Note: a listener for the click event is always added.

Initial Zoom Level

Initial zoom level (0..23) if no data is loaded. Default is 2. If data is loaded, this attribute has no effect.

Initial Map Center

Set the latitude and longitude as a pair of numbers, delimited by commas, to be used to position the map on page load, if no pin coordinates have been provided by the page item. Default is 0,0. If data is loaded, this attribute has no effect. Note: number values must be expressed using dot (.) as the decimal separator.

Rows Per Batch

Load the pins in multiple ajax calls, with this number of rows per batch. Setting this attribute increases the overall time required to load all the data, but allows the map to start showing some pins earlier, making it more user-friendly.

As each batch is received, the map will expand the bounds (pan & zoom) to show the new pins.

Leave blank to cause all the pin data to be loaded in a single ajax call. The map will wait until the entire data set is downloaded before rendering the pins. This is the fastest way, although for large data sets the user might get impatient.

This attribute is not applicable for the Heatmap visualisation, which needs to load all the data before it can be rendered visually.

Language

By default, the map uses the user's preferred language setting as specified in the browser, when displaying textual information such as the names for controls, copyright notices, driving directions and labels on maps. In most cases, it's preferable to respect the browser setting and leave this attribute blank.

To override the user's preferred language, set the language code; e.g. ja for Japanese. The list of supported languages may be found here.

Substitution syntax allowed, e.g. &P1_LANGUAGE. Note that the page must be reloaded if the language is changed.

Region

When you load the map it applies a default bias for application behavior towards the United States. If you want to serve different map tiles or bias the application (such as biasing geocoding results towards the region), you can override this default behavior by setting the Region attribute.

The region parameter accepts Unicode region subtag identifiers which (generally) have a one-to-one mapping to country code Top-Level Domains (ccTLDs). Most Unicode region identifiers are identical to ISO 3166-1 codes, with some notable exceptions. For example, Great Britain's ccTLD is "uk" (corresponding to the domain .co.uk) while its region identifier is GB. Try this demo to experiment with the changes on the map when you update the region parameter.

As the developer of an application using Google Maps it is your responsibility to ensure that your application complies with local laws by ensuring that the correct region localization is applied for the country in which the application is hosted.

Restrict to Country code

Used when performing an address search. Leave blank to allow geocoding to find any place on earth (see example below). Set to country code (see https://developers.google.com/public-data/docs/canonical/countries_csv for valid values) to restrict geocoder to that country. You can load a table of country codes in your application by running the countries_data.sql script.

Map Style

Change the default map style. You can generate your own map styles with this tool or copy one from a site like https://snazzymaps.com/.

Dissipating (Heatmap)

Only applicable if Visualisation is Heatmap. Specifies whether heatmaps dissipate on zoom. Yes means the radius of influence of a data point is specified by the radius option only. When dissipating is disabled, the radius option is interpreted as a radius at zoom level 0. Default is No.

Opacity (Heatmap)

Only applicable if Visualisation is Heatmap. The opacity of the heatmap, expressed as a number between 0 and 1. Default is 0.6.

Radius (Heatmap)

Only applicable if Visualisation is Heatmap. The radius of influence for each data point, in pixels. Default is 5 pixels.

Travel Mode (Directions)

Only applicable if Visualisation is set to "Directions". Select the mode of transport when showing directions. Possible values include Driving (default), Walking, Bicycling, and Transit (public transport).

Optimize Waypoints (Directions)

Only applicable if Visualisation is Directions. If set to Yes, the intermediate waypoints may be reordered to reduce cost. Default is No (waypoint order is retained).

Drawing Mode

Setting any of these Drawing Modes enables the Google Maps Drawing Library. A button will be added to the top of the map for each shape, allowing the user to select a shape to draw.

The shapes the user has drawn can then be retrieved from the plugin as a GeoJSON document, which can later be re-loaded onto the map.

Available options include:

  • marker
  • polygon
  • polyline
  • rectangle
  • circle

When drawn, a circle is merely rendered as a point (at the circle's center) with a hidden "radius" property. I realise this is not terribly user-friendly but is included for completeness. Note that circles are not supported by the GeoJSON data format anyway.

Any shapes drawn, loaded or retrieved using the drawing library are independent of the pins that might also be shown in the map derived from the report query. In particular, retrieving the shapes as a GeoJSON document does not include points for the pins that may have been loaded by the region query, as these pins are not rendered using the drawing library.

Default Map Type

Initial map type shown on page load. The user may change the map type.

  • Roadmap (default)
  • Satellite
  • Hybrid
  • Terrain

Gesture Handling

This attribute allows you to select how the map responds to touch gestures on a mobile device. Mobile web users often get frustrated when trying to scroll the page, but an embedded map captures their swipe and pans the map instead. This can even lead to users getting stuck on the map and having to reload the page in order to get back to the rest of the page. This option allows you to make scrolling more intuitive and less frustrating map interaction experience on mobile browsers. This may be set to one of the following values:

  • "cooperative": Two-finger touch gestures pan and zoom the map, as do all mouse gestures. One-finger touch gestures are ignored by the map. In this mode, the map cooperates with the page, so that one-finger touch gestures can pan the page.
  • "greedy": All touch gestures pan or zoom the map.
  • "none": The map cannot be panned or zoomed by user gestures.
  • "auto" (default): Gesture handling is automatically set to either cooperative or greedy, depending on whether the page is scrollable or not (defined by a comparison of the page body dimensions and the window dimensions).

If the page is scrollable, "auto" sets the gesture handling mode to cooperative. If the page is not scrollable, "auto" sets the gesture handling to greedy. If the map is in an iFrame, "auto" sets the gesture handling to cooperative because the API can't determine whether the page is scrollable.

Escape special characters

This is relevant only to the "flex fields", if supplied in the SQL Query. By default any special characters (such as < and >) will be escaped prior to sending to the client, in order to protect against XSS attacks and to allow the original data to be rendered exactly as entered. To disable this escaping, set this attribute to No.

Messages - No Data Found Message

Set this to customise the message shown in a popup InfoWindow if the SQL Query returns no rows.

Advanced - Initialization JavaScript Code

Set this to run additional javascript code when the Google Map object has been instantiated. Use this.map to refer to the google.maps.Map object. For example, to hide most of the default UI elements that Google Maps renders on the map:

this.map.setOptions({
    "disableDefaultUI": true
});

You can overwrite some plugin attributes (including a lot of the options that may have been set declaratively) here as well, such as this.options.maximumRows, this.options.rowsPerBatch, this.clickZoomLevel, etc. - but not all options can be changed this way, if their effect on the plugin has already been set. Feel free to experiment and see.

Refer also to Other Attributes below for options that can be set using JavaScript.

NOTE: since this code is run before the map data is loaded, some things you might do here will have no effect, e.g. if you set the map position or zoom level, when the map data is loaded the map will most likely be moved and zoomed accordingly.

To have some code run after the data is loaded, create a Dynamic Action on the mapLoaded event.

Other Attributes

These attributes are not set declaratively on the plugin. They can be set by adding code to the JavaScript Initialization Code.

directionsPanel

Set this to nominate a <div> on your page in which to display human-readable turn-by-turn directions when a Route Map is shown in the map. For example:

this.options.directionsPanel = "directionspanel";

For the above example to work, you would add a region to your page, with the following contents:

<div id="directionspanel"></div>

iconBasePath

Set this to a string which will be prepended to the icon column from your query. This is useful if all your icons are at the same location; setting this can significantly reduce the volume of data downloaded to the client, since you don't need to include the full path with each row of data.

this.options.iconBasePath = 'https://maps.google.com/mapfiles/kml/shapes/';

If all your icons are loaded in your Application Static Files, you can set it like this:

this.options.iconBasePath = '#APP_IMAGES#';

infoLayerFormatFn

Set this to a JavaScript function that will be called for each Info Layer. This is only applicable if Visualisation is InfoLayer (or the showInfoLayer option is true). For example:

this.options.infoLayerFormatFn =
    function(layer, marker) {

        //layer points to a MapOverlay object
        layer.options.verticalAlign = "bottom";
        layer.options.horizontalOffset = -10; //pixels
        layer.options.minZoom = 2; // hide the info layer if zoomed out past this level

        //marker points to the marker info object
        if (marker.data.name == "HOME") {
            layer.options.div.classList.add("homestyle");
        }

    };

The MapOverlay object provides the following interface:

  • layer.pos = get or set the marker position for the info layer; the content will not be scaled
  • layer.bounds = get or set the bounds for the info layer; the content will be scaled to match this range of lat,lng coordinates (e.g. to show a map image on top of the map)
  • layer.content = get or set the content of the info layer div
  • layer.div = returns a reference to the info layer div container
  • layer.options = get or set the options for the layer: 
    {
    horizontalAlign  : "left" / "center" / "right" (pos only)
    verticalAlign    : "top" / "middle" / "bottom" (pos only)
    horizontalOffset : pixel offset (x) (pos only)
    verticalOffset   : pixel offset (y) (pos only)
    minZoom          : (0..23) hide if zoomed out past this level
    maxZoom          : (0..23) hide if zoomed in past this level
    onClickHandler   : function to call if overlay clicked (set to null to stop the info layer responding to clicks)
}
  • layer.hide() = hide the info layer
  • layer.show() = show the info layer
  • layer.toggle() = hide or show the info layer

markerFormatFn

Set this to a JavaScript function that will be called for each marker. It may be used to customise the format of the marker using whatever logic you may require. For example:

this.options.markerFormatFn =
    function(marker) {

        // if id is even, change the icon to a circle; odd are squares
        var iconUrl = 'https://mt.googleapis.com/vt/icon/name=icons/spotlight/'
            + ((marker.data.id % 2 == 0)
               ? 'spotlight-waypoint-blue.png&scale=1.5'
               : 'spotlight-waypoint-a.png&scale=1.5');
        marker.icon = {
            url: iconUrl,
            anchor: new google.maps.Point(14,16)
        };

        // you can change other attributes of the marker as well
        marker.title = marker.title.toUpperCase();
  
        // we can call google.maps.Marker object methods as well
        marker.setOpacity(0.5);

        if (marker.title == 'HOME') {
            // we can shift the marker position
            marker.setPosition( {lat: -31.82531, lng: 115.84366} );
        }
    };

If your logic needs to access the data from your query's "flex" fields, these may be accessed in the marker's data:

this.options.markerFormatFn =
    function(marker) {
        if (marker.data.attr01 == 'hospital') {
            marker.icon = 'https://maps.google.com/mapfiles/ms/icons/hospitals.png';
        }
    };

You can refer to the flex fields using marker.data.attr01, marker.data.attr02, ... marker.data.attr10. They will all be strings so if you need to do math on them you would convert them to numbers first (e.g. using parseInt or parseFloat).

showInfoLayer

If true, the info column is rendered directly in a div on the map at the location of the pin. This option is set to true if the Visualisation is set to InfoLayer.

this.options.showInfoLayer = true;

showInfoPopups

If true, when the user clicks on a pin, an Info Window will popup with the content of the info column rendered within it. This option is set to true if the Visualisation is any of the pin-type visualisation, false if the Visualisation is set to InfoLayer.

this.options.showInfoPopups = true;

showPins

If true, a pin is rendered at the location of each data point. This option is set to true if the Visualisation is any of the pin-type visualisation, false if the Visualisation is set to InfoLayer.

this.options.showPins = true;

spiderfier options

You can override the default options for the Spiderfier visualisation by setting this.options.spiderfier. For example:

this.options.spiderfier.keepSpiderfied = false;
this.options.spiderfier.basicFormatEvents = false;

Documentation of the Spiderfier options may be found here.

spiderfyFormatFn

Set this to a JavaScript function to be used to change the format of markers when they are spiderfied or unspiderfied by the Spiderfier visualisation. For example:

this.options.spiderfyFormatFn =
    function(marker, status) {
        var iconURL = (status == OverlappingMarkerSpiderfier.markerStatus.SPIDERFIED) ?
            'spotlight-waypoint-blue.png' :
            'spotlight-poi.png';
        marker.setIcon({url: 'https://mt.googleapis.com/vt/icon/name=icons/spotlight/' + iconURL});
    };

Note: if options.spiderfier.basicFormatEvents = true, status will be SPIDERFIED or UNSPIDERFIED; if options.spiderfier.basicFormatEvents = false, status will be SPIDERFIED, SPIDERFIABLE, or UNSPIDERFIABLE.

geoJson Feature options

featureColor

Color to use for features that are not selected.

this.options.featureColor = '#cc66ff';

featureColorSelected

Color to use for features that are selected.

this.options.featureColorSelected = '#ff6600';

featureSelectable

Set this to false to stop geoJson features responding to the click event by the user. Default is true (when the user clicks a feature, it will be marked and styled as "selected" and the selectFeature / unselectFeature events will fire).

this.options.spiderfier.featureSelectable = false;

featureHoverable

Set this to false to stop geoJson features responding to the hover event by the user. Default is true (when the mouse hovers over a feature, it will be styled differently and the mouseoverFeature / mouseoutFeature events will fire).

this.options.spiderfier.featureHoverable = false;

featureStyleFn

By default, features will be styled using the featureColor / featureColorSelected options. You can override the styling of the features by providing a JavaScript function that, given a feature object, returns a google.maps.Data.StyleOptions object.

this.options.featureStyleFn =
    function(feature) {
        var color;
        if (feature.getProperty('isSelected')) {
            color = "#de90c5";
        } else if (feature.getProperty('attr01')=="xyzzy") {
            color = "#eb4909";
        } else {
            color = "#d12a9c";
        }
        return /** @type {!google.maps.Data.StyleOptions} */({
            fillColor    : color,
            strokeColor  : color,
            strokeWeight : 2
        });
    };

v0.x Attributes Removed in v1.0

These attributes were previously available in the beta releases of the plugin. Their behaviour has been changed or removed in v1.0. If you are upgrading from any beta release to v1.0 or later, if you used any of these attributes you will need to make some changes.

  • Set Item Name to ID on Click

    REMOVED IN v1.0 - instead, use a dynamic action on the markerClick event - refer to Plugin Events Reference

  • Synchronize with Item

    REMOVED in v1.0 - instead, use a dynamic action on change of the item that calls gotoPosByString - refer to Plugin API Reference

  • Marker Icon

    REMOVED in v1.0 - instead, specify an icon in the query for each pin

  • Circle Radius Item

    REMOVED in v1.0 - instead, set options.markerFormatFn to a javascript function that styles the marker

  • Pan on click

    MOVED in v1.0 to Options (see above)

  • Geocode Item

    REMOVED in v1.0 - instead, use a dynamic action on change of the item which calls gotoAddress - refer to Plugin API Reference

  • Address Item

    REMOVED IN v1.0 - use dynamic action instead which calls getAddress - refer to Plugin API Reference

  • Geolocate

    REMOVED IN v1.0 - use dynamic action instead which calls geocode - refer to Plugin API Reference

  • Geolocate Zoom

    REMOVED in v1.0 - use dynamic action instead

  • Directions Origin Item

    REMOVED IN v1.0 - use showDirections API instead

  • Directions Destination Item

    REMOVED IN v1.0 - use showDirections API instead

  • Show Calculated Distance

    REMOVED IN v1.0 - use dynamic action on directions event instead

  • Show Calculated Duration

    REMOVED IN v1.0 - use dynamic action on directions event instead

  • Attribute1

    REMOVED IN v1.0 - use label column in SQL query instead

  • Zoom enabled (condition)

    MOVED in v1.0 to Options (see above)

  • Pan enabled (condition)

    MOVED in v1.0 to Options (see above)

  • Number of Rows

    REMOVED in v1.0 - use Maximum Rows (Component) attribute instead

Clone this wiki locally