Deprecated for new sites

This module was for A2 0.5.x. For new projects, use the apostrophe-places module.

apostrophe-map

apostrophe-map adds interactive maps to the Apostrophe content management system. apostrophe-map provides both backend and frontend components, including a friendly UI built on Apostrophe's rich content editing features.

See the apostrophe-sandbox project for a demo of usage. Setup is similar to apostrophe-blog or apostrophe-snippets. The geocoder is automatically started.

Special map-related options to the get method

The "get" method of the maps module accepts these options, in addition to everything snippets.get and pages.get will accept:

geo: a GeoJSON point. When this option is passed, results are sorted by distance from this point.

maxDistance: results are restricted to points within this many meters of "geo". maxKm: same for kilometers. maxMiles: same for miles.

Subclassing the map

The map module's browser-side JavaScript can now be easily subclassed and extended.

Prior to 3/12/15 this was very difficult due to the timing of the way the map object was constructed.

Here is an example of code that overrides the method that generates an info box:

// This code lives at your project level, in
// lib/modules/apostrophe-map/public/js/content.js

var superAposGoogleMap = AposGoogleMap;

AposGoogleMap = function(item, id, mapOptions) {
  var self = this;
  superAposGoogleMap.call(self, item, id, mapOptions);
  self.activateInfoBox = function(item) {
    alert('Do this instead of displaying the info box');
  };
};

Note the use of the "super pattern," much as we do on the server side when extending methods of Apostrophe modules.

You'll find that the browser-side code in content.js has been broken down into many individual methods, all of which can be easily overridden in this way.

bc break, June 5th, 2014: GeoJSON, map locations and your JavaScript

We've made a change to the way the map module stores coordinates. This change enables the use of a 2dsphere index for fast searches for addresses and other locations. And we've introduced cool options that leverage that. But, there's a bc break required.

Previously there was a "coords" property which contained "lat" and "lng" properties.

Now, we're storing a GeoJSON point in a "geo" property.

It looks like:

location.geo = { type: 'Point', coordinates: [ longitude, latitude ] };

IMPORTANT: LONGITUDE COMES FIRST.

(MongoDB's choice, not ours, but it does fit with the newer convention that X always comes before Y, even if you're talking about maps.)

FOR OLD SITES, YOU SHOULD RUN "node app apostrophe:migrate", otherwise the map module will have to geocode your coordinates again based on their address field. Which is not the end of the world, but it's nice to skip it especially if you have a lot of them.

IF YOU OVERRODE OUR BROWSER-SIDE JAVASCRIPT, YOU WILL NEED TO FIX YOUR CODE to use the new .geo property instead of the old .coords property.

Example:

coords = new google.maps.LatLng(item.geo.coordinates[1], item.geo.coordinates[0]);

The .coords property in old sites will hang around, because it's not hurting anyone and migrations should be as gentle as possible. But it won't be updated anymore, so don't be fooled.

Dynamic loading

You no longer need to add script tags for the Google Maps API to your base.html file. Instead, these dynamically load on their own, and only when they are actually needed.

Older base.html files that do load these scripts the hard way will still work, but you are slowing your users down on every page, so stop doing that.

Configuring the geocoder

You may pass configuration to the node-geocoder npm module used to look up addresses via the geocoder option to the apostrophe-maps module. The default geocoding provider is Google. You will need to configure the apiKey property for domains that have not used the Google Maps API before.

In addition, the dailyLimit and rateLimit properties of the geocoder option can be used to limit the queries per day and per second, respectively. These default to 2500 and 10 to stay on the good side of Google's free API limits.

Caching

To minimize times when you bash into Google's rate limit when rapidly testing in development, Geolocation results are cached for one day. There is very little downside to this (addresses don't move around very much), but you can set the cache lifetime in seconds as {geocoder: { cacheLifetime: 86400 } }. The default is one day (86,400 seconds).