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:

  • Developer mode: loads the unminified Javascript and CSS, handy for debugging. Adding #maps_debug to the URL also turns on debug mode in the browser.
  • 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.

How the other Maps add-ons build on Maps ​

All of them need Maps to be installed.

  • Maps Fieldtype: 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.
  • Maps Locator: a store locator. It keeps track of the locations saved in Maps Fieldtype fields (updated when an entry is saved) and uses the Maps geocoder to look up what visitors search for.
  • Maps Route: the route tags ({exp:reinos_maps:route} and {maps:add_route}) and the route providers are part of Maps.
  • Maps Importer: a DataGrab fieldtype to import locations into a Maps Fieldtype 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.
  • Nothing in the log: many messages (e.g. "No result found for ...") are logged as a notice. Set What to log to Everything while debugging.
  • 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.