Skip to content

Latest commit

 

History

History
246 lines (182 loc) · 9.8 KB

README.md

File metadata and controls

246 lines (182 loc) · 9.8 KB

What's new in cordova-google-maps-plugin Version 2?

Version 2 of the plugin has been improved alot from version 1.

Change 1: Multiple maps

As you may know, the new version supports multiple maps in the same HTML page. However one map takes up a large amount of memory, so I recommend a maximum of two or three maps on one page. If you don't use a map then remove it - that will save memory!

Change 2: Multiple pages

Version 1.x only supported a single HTML file (typically index.html). The new version supports multiple HTML files (such as index.html, page1.html, page2.html ...etc) You don't need to clean up the maps if you change HTML files. The plugin will do that automatically.

However, changing tab page in the same HTML is a different story. You still need to use map.setVisible(true/false).

Change 3: Recognise all HTML elements

Version 1.x only supported the map div. The new version recognises all the HTML elements on the page. It means you don't need to execute map.setClickable(true/false) when a HTML dialog is popped up on the map div.

** Here is a tip ** If the plugin does not recognise your HTML elements on the map div, specify the following css:

.dialog {
    position: fixed;
    z-index: 1000; //any value is fine
}

HTML elements that have position:fixed always take priority in the maps plugin. (You don't need to do this usually (I believe))

Change 4: Save battery life

The problem with version 1.x was the KeepWatching Timer. This timer periodically watches HTML element positions in the map div. However the timer runs continuously, regardless of whether there is user input in your app or not. This affects your device battery life.

In the new version, the timer stops automatically if the user does not touch on the map for a while. If the user touches on the app again then the timer starts. If there are no changes for a while then the timer stops again.

If you need to start the timer programmatically, you can do so like this:

cordova.fireDocumentEvent('plugin_touch', {});

or

var event = document.createEvent('plugin_touch');
event.initEvent(eventName, false, false);
document.dispatchEvent(event);

NOTE: The plugin V2 now uses plugin_touch instead of touch_start

Change 5. Performance improvements

Another big problem of version 1.x was that all (most) native code ran on the UI thread (or ran on the WebCore thread). The reason for this is the Google Maps Native API's require it. However I tested lots and rewrote almost the entire codebase in both native and Javascript, so most of the code runs on the background thread. And most of the code now also runs in parallel.

For example, adding multiple markers on a map works like this.

In the end, adding multiple markers becomes a lot faster.

npm version1.3.9 v1.3.9 Master branch / commit caf6ec1099 v2-beta / commit 906fc04

47.1 sec
1.0 sec
0.5 sec

See more information at issue #835: Performance problems when adding many markers

If you don't understand this you can skip it. Just remember that the performance has been improved.

Change 6. Split JS files

The version 1.x code of the Javascript is googlemaps-cdv-plugin.js The file is 2873 lines long. Wow, it's too large and not suitable for maintenance...not even for me!

I have split the JS files for each class (such as Marker.js, Circle.js, etc): https://github.com/mapsplugin/cordova-plugin-googlemaps/tree/multiple_maps/www

You can now easily debug your app :)

Change 7. Introduce BaseArrayClass

If you are familiar with the Google Maps Javascript API v3, you probably know the MVCArray class The benefit of this class is you can monitor the events: insert_at, set_at, and remove_at. Using this class your code will be simpler.

Change 8. Property synchronizing

This is really useful. Most getXXXX() methods return the values as a normal Javascript object.

For example, in version 1.x:

marker.getPosition(function(position) {
   // you have to wait for the callback
});

In version 2.0-beta:

var position = marker.getPosition();

You know what? Since the marker (and polyline, polygon...etc) extend the BaseClass (which is a MVC class), you can monitor like this:

markers[0].on("position_changed", onPositionChanged);
markers[1].on("position_changed", onPositionChanged);
markers[2].on("position_changed", onPositionChanged);

function onPositionChanged() {
  var marker = this;
  var position = marker.getPosition();
}

However, map.getVisibleRegion() does not support this, you still have to use a callback. As of the v2.0-beta2, you can use the map.getVisibleRegion() method synchronously.

Change 9. Chain programming

In version 2.0, most setXXX() methods can be chained.

marker.setPosition({"lat": ...., "lng": ....}).setTitle("Hello");

change 10. Add more events, and renamed:

Version 1.x events

event name Android iOS
MAP_CLICK YES YES
MAP_LONG_CLICK YES YES
MY_LOCATION_CHANGE YES NO
MY_LOCATION_BUTTON_CLICK YES YES
INDOOR_BUILDING_FOCUSED YES YES
INDOOR_LEVEL_ACTIVATED YES YES
CAMERA_CHANGE YES YES
CAMERA_IDLE NO YES
MAP_READY YES YES
MAP_LOADED YES NO
MAP_WILL_MOVE NO YES
MAP_CLOSE YES YES
OVERLAY_CLICK YES YES
INFO_CLICK YES YES
MARKER_DRAG YES YES
MARKER_DRAG_START YES YES
MARKER_DRAG_END YES YES

Version 2.x events

event name Android iOS arguments[0]
MAP_READY YES YES none
MAP_CLICK YES YES LatLng
MAP_LONG_CLICK YES YES LatLng
MY_LOCATION_BUTTON_CLICK YES YES none
INDOOR_BUILDING_FOCUSED YES YES none
INDOOR_LEVEL_ACTIVATED YES YES building information
CAMERA_MOVE_START YES YES true if the camera move start by gesture
CAMERA_MOVE YES YES CameraPosition
CAMERA_MOVE_END YES YES CameraPosition
POLYGON_CLICK YES YES LatLng(clicked position)
POLYLINE_CLICK YES YES LatLng(clicked position)
CIRCLE_CLICK YES YES LatLng(clicked position)
GROUND_OVERLAY_CLICK YES YES LatLng(clicked position)
INFO_CLICK YES YES LatLng(marker position)
INFO_LONG_CLICK YES YES LatLng(marker position)
INFO_CLOSE YES YES LatLng(marker position)
INFO_OPEN YES YES LatLng(marker position)
MARKER_CLICK YES YES LatLng(marker position)
MARKER_DRAG YES YES LatLng(marker position)
MARKER_DRAG_START YES YES LatLng(marker position)
MARKER_DRAG_END YES YES LatLng(marker position)

Change 11. Set background color

Use plugin.google.maps.environment.setBackgroundColor() to set the background color.

Change 12. Geocoding / reverse geocoding

You can do Geocoding like this:

plugin.google.maps.Geocoder.geocode({
  "address" : [
     "address1", "address2" ... "addressN"
  ]
}, function( mvcArray ) {

  mvcArray.on('insert_at', function(index) {
     console.log( mvcArray.getAt(index) );
  });

});

Change 13. Add some features

I forgot too much. See the demo APK.

Change 14. Methods still in development

map.showDialog(), map.closeDialog(), and map.addKmlOverlay() are still in development and are not ready yet.

Change 15. UIWebView & WKWebView

Both are Supported.

Crosswalk is not confirmed yet.

I think I may have missed somethin - I will post if I remember.