Addons by Reinos

Appearance

How it works ​

Maps shows interactive Leaflet maps in your templates. The map is drawn in the visitor's browser, while addresses are looked up (geocoded) on your server and remembered in a cache. The steps below explain what happens and where things can go wrong.

Rendering a map ​

  • Place {exp:reinos_maps:html_header} in the <head> of your page. It adds the styling, and when the Google Maps or Apple Maps tile is enabled in the CP, it also loads their scripts with your API key. See HTML header tag.
  • {exp:reinos_maps:map}...{/exp:reinos_maps:map} reserves the spot for the map on the page (with the ID reinos_map_1, reinos_map_2 for the second map, etc.). See Map tag.
    • The tile from the tiles param must be enabled in the CP. When it is not, the map falls back to openstreetmap (if that one is enabled); when no usable tile is left, the map is not shown.
    • A center:address is turned into a location on the server (see below).
  • The tags inside the map, like {maps:add_marker}, {maps:add_polygon}, {maps:add_geojson} or {maps:add_route}, add things to that map. They only work inside the {exp:reinos_maps:map} tag pair.
  • Place {exp:reinos_maps:html_footer} before </body>, after all maps. See HTML footer tag.
  • When the page is done, Maps collects everything that was set up for all maps on the page and outputs it at the spot of the html_footer tag. That's why the footer tag is required and must come after the maps. This only happens for a full page, not for a template that is loaded on its own via AJAX.
  • In the browser the map is drawn with its tiles and controls, and then the markers, shapes, GeoJSON and KML are added. You can hook into this with the events and methods of the Javascript API.

Geocoding and caching ​

  • Addresses are looked up by the providers that are enabled in the CP (openstreetmap by default; google_maps and bing_maps need an API key). When more providers are enabled and one finds no result, the next one is tried. IP addresses are looked up with free IP-based services. See Providers and Tiles.
  • Every result is saved in the cache (CP → Cache) and reused until it is older than the Geocode cache time setting; then the address is looked up again.
  • With the Cache setting enabled, results are also kept in a file cache (the Cache location setting) for the Cache time setting, which makes it a bit faster.
  • The Geocoder tag, the Geocoder API and the geocode method of the Javascript API use the same lookup and share the same cache.
  • Routes ({exp:reinos_maps:route} and {maps:add_route}) are calculated by the route provider set in the CP (Google Maps or Bing Maps) and drawn as a line on the map.

CP settings ​

See CP overview for all settings. In short:

  • Debugging: add #maps_debug to the URL to log the Javascript API calls in REINOS_MAPS.apiLog. The Javascript and CSS are one minified bundle, with a source map for the browser's developer tools. (The Developer mode setting is removed in v5.0.0.)
  • Data transfer: how the server connects to the providers, HTTP or cURL.
  • What to log: only errors, Everything (errors and notices) or Nothing. Logs are shown in CP → Logs and in the EE template debugger.
  • Cache / Cache time / Geocode cache time / Cache location: see above.
  • Weather API: the OpenWeatherMap key for the weather param.
  • Providers / Route Providers / Tiles: what is used for looking up addresses, for routes and for the map tiles. A tile must be enabled here before you can use it in the tiles param.

The fieldtype, routes and the other Maps add-ons ​

  • Fieldtype: Maps comes with a fieldtype to store markers, polygons, etc. per entry. Its front-end tag shows them with the Maps tags and uses the providers and tiles from the Maps CP. (Part of Maps from v5.0.0, before it was the separate Maps Fieldtype add-on.)
  • Routes: the route tags ({exp:reinos_maps:route} and {maps:add_route}) and the route providers are part of Maps.
  • Maps Locator: a store locator, a separate add-on that needs Maps. It keeps track of the locations saved in Maps fields (updated when an entry is saved) and uses the Maps geocoder to look up what visitors search for.
  • Maps Importer: a DataGrab fieldtype to import locations into a Maps field, using the Maps geocoder.

Common pitfalls ​

  • No map is shown: check that {exp:reinos_maps:html_header} and {exp:reinos_maps:html_footer} are in the template (the footer after all maps), and that the tile from the tiles param is enabled in the CP. Check the browser console for Javascript errors. A missing header or footer tag is also logged as an error in the Maps log. (from v5.0.0)
  • Nothing in the log: errors (e.g. "No result found for ..." or "No active tiles given") are logged with What to log set to only errors. Set it to Everything while debugging to also see notices, such as whether a result came from the cache.
  • A marker is missing: the address could not be found (see the log), or the provider needs a valid API key. A wrong result stays in the cache until the Geocode cache time has passed; delete it in CP → Cache to look it up again.
  • Google or Bing errors: the API key is missing, restricted the wrong way, or the needed API is not enabled. The Google key for geocoding needs the Geocoding API and an IP restriction, the key for the tiles an HTTP referrer restriction.
  • The map is shown but the markers or shapes are not: the tags are placed outside the {exp:reinos_maps:map} tag pair, or the template is loaded on its own via AJAX, so the last step that outputs the map data is skipped.
  • Complex HTML in a popup breaks the tag: use the encode tag.
  • A map inside a hidden element (tab, modal) is drawn with the wrong size: call REINOS_MAPS.api('refresh', {mapID: 'reinos_map_1'}) once it is visible.
  • Focus on the current location (focus_current_location) only works on HTTPS.