Addons by Reinos

Appearance

How it works ​

The fieldtype of Maps adds a field in which editors draw a map per entry: markers, polylines, polygons, circles and rectangles, plus some map settings. It is part of Maps (before v5.0.0 it was the separate Maps Fieldtype add-on): the map in the CP and on the front-end is a Maps map, and the tiles, geocoding and map scripts all come from Maps. Below is the step-by-step process and where problems can come from.

What is stored where ​

  • The map of an entry is saved in the field itself, like any other field (also inside a Grid or Bloqs cell). It holds all markers, shapes, their tooltips and popups, and the map settings (zoom, center, tiles and the options from Edit map settings). For a marker with a custom icon, the full URL of that icon is saved.
  • The value is encoded, so the EE search and search:field params can't search in it. Use Maps Locator to search on location.
  • Field settings (icon dir/url, location, height, max markers, permissions, ...) are part of the EE field settings, see Fieldtype.
  • Add-on settings: only What to log. Errors are field data that can't be read and requests for the map editor with invalid field settings; notices are entries that were not saved because of the field validation (max markers, layer types, Entry API). Problems in the editor itself show up in the browser console.

When you import data yourself (e.g. with the Entry API), use the same structure the field saves:

json
[{
  "markers":    [{"lat": 52.37, "lng": 4.89, "icon": null, "tooltip": "Office", "content": "base64:PHA+SGk8L3A+"}],
  "polylines":  [{"color": "...", "opacity": 1, "weight": 3, "latlngs": [[52.3, 4.8], [52.4, 4.9]], "tooltip": "", "content": ""}],
  "polygons":   [{"color": "...", "opacity": 1, "weight": 3, "fillColor": "...", "fillOpacity": 0.2, "latlngs": [[52.3, 4.8], ...], "tooltip": "", "content": ""}],
  "circles":    [{"color": "...", "...": "...", "lat": 52.3, "lng": 4.8, "radius": 500, "tooltip": "", "content": ""}],
  "rectangles": [{"color": "...", "...": "...", "latlngs": [[ne_lat, ne_lng], [sw_lat, sw_lng]], "tooltip": "", "content": ""}],
  "map": {"zoom": 10, "max_zoom": 18, "scroll_wheel": true, "zoom_control": true, "zoom_control_position": "topleft",
          "scale_control": true, "scale_control_position": "bottomleft", "overlay_html": "", "overlay_position": "right",
          "tiles": ["openstreetmap"], "center": [52.37, 4.89]}
}]
  • icon is the full URL of a marker icon, or null for the default icon.
  • A popup (content) is base64: followed by the base64 encoded HTML; an empty popup is "". The radius of a circle is in meters.
  • Always include circles, rectangles and map.center (they may be empty) when you write the data yourself, otherwise the map breaks when the entry is opened in the CP. The Entry API adds them for you, see Webservice.

Editing an entry in the CP ​

  • The field first shows "Loading your Map". A map is only loaded once it is visible on the screen, so a map in a hidden tab or a collapsed Grid row loads when you open it.
  • To build the map, the CP makes a request to the front-end of your site (your site_url). That's also where the permissions of the member are checked. If that request fails, the map keeps loading (see Common pitfalls).
  • The saved markers, shapes and map settings are added to the map. When the field is empty, the map is centered on the Location of the field settings.
  • The search button looks up an address with the Maps geocoder; you can also type lat,lng. The chosen result becomes a new marker.
  • Every change on the map (layers, zoom, center, tiles and Edit map settings) is kept in the field and saved when you save the entry.
  • Max markers limits the markers you can draw or add with the search in the CP, and is checked again when the entry is saved.

Rendering the field in a template ​

See the Tag page for all params and variables.

  • {your_field} (or the tag pair) renders a Maps map with all saved markers and shapes. So {exp:reinos_maps:html_header} and {exp:reinos_maps:html_footer} are required, just like for any Maps map, and everything from How Maps works applies. An empty field outputs nothing.
  • A tag param always wins over what is saved in the entry. Params you don't set come from the map settings saved in the entry (the tiles, the zoom, the max zoom, the center, the scroll wheel, the zoom and scale control and their positions, and the overlay). When the entry has no tiles or zoom saved, the Set default Tile provider and Default zoom level field settings are used.
  • Tooltips may use the variables of the entry (e.g. {title}). Other tags ({exp:...}) in a tooltip or popup are not run, they are shown as text.
  • Tooltips, popups and the overlay are cleaned with the ExpressionEngine XSS filter when the entry is saved (and when the map is shown in the CP): scripts, event handlers like onclick and javascript: links are removed, normal HTML stays.
  • The variable pairs (:markers, :polylines, :polygons, :circles, :rectangles, :routes, :map) and :has / :markers_latlngs only output the data; they don't render a map. Use them inside your own {exp:reinos_maps:map} tag to style the layers yourself (see Examples).

Maps, routes and Maps Locator ​

  • Maps: the fieldtype uses its tags, its map scripts, its tiles (the Set default Tile provider setting and the Edit map settings modal only list the tiles that are enabled in Maps), its geocoder (location and search) and its log.
  • Routes: the {your_field:routes} pair turns the markers into from (first marker), stops and to (last marker), which you pass to {maps:add_route}, see the example. The fieldtype itself does not calculate routes.
  • Maps Locator: indexes every marker of the field as a location when an entry is saved. See Maps Locator: how it works.
  • Maps Importer: imports data into a Maps field with DataGrab.

Grid, Channel Form and other modules ​

See Supported modules.

  • The field can be used in channel fields, Grid, Fluid and Bloqs, and in Low Variables.
  • Channel Form (docs): the field works like in the CP, so it needs the EE assets (include_assets="yes"). Visitors that are not logged in get the permissions of the Guests role.
  • Entry API: the data you send is saved as is, so it must use the structure above (see Webservice).

Permissions ​

See Permissions. The toolbar depends on the field settings and all roles of the member (one selected role is enough). Roles that are not selected get no toolbar buttons. By default only Super Admin is selected, and Super Admins don't get the buttons automatically. The member is recognised by the front-end login, so when the CP runs on another domain than the site_url, the member is treated as a Guest.

Hide edit option only removes the Edit item from the right-click menu; Delete and moving/reshaping layers stay available.

The hook ​

Developers can run their own code after an entry with a Maps field is saved, see Hooks. Maps Locator uses this.

What it adds to and depends on from other add-ons ​

  • It does not change Maps or other add-ons.
  • It is part of Maps: when you used the separate Maps Fieldtype add-on, update Maps and then uninstall the old add-on, see Upgrading to 5.0. Your fields and their data stay the same. Data of the old Gmaps Fieldtype is converted with the migration tool instead, see Migrate from Gmaps.

Common pitfalls ​

  • "Loading your Map" keeps spinning: the map is not visible yet, or the request to the front-end failed. Check the browser console and the Network tab: a wrong site_url (another domain, http vs https), a front-end that is blocked (maintenance mode, basic auth, a redirect), or a PHP error (check the Maps log and the PHP error log). After an upgrade, clear the cache (see FAQ).
  • Console: "It seems that the Maps cannot be loaded": the default tile of the field is not enabled in Maps (or Maps failed to load).
  • No toolbar buttons: the role of the member is not selected in the field settings, see Permissions.
  • The icon list only shows "Default": the Icon dir folder doesn't exist or is empty. Check Icon dir and Icon url ({base_path} is replaced by the base_path config item, {base_url} by the site_url); by default they point to the icons that come with Maps (themes/user/reinos_maps_fieldtype/assets/markers/, this folder keeps its old name). The full icon URL is saved per marker, so after a domain change old markers still point to the old URL.
  • Search finds nothing: the Maps geocoder has no result; check the providers and the log in Maps.
  • No map on the front-end: html_header/html_footer missing, the field is empty, the saved tile is no longer enabled in Maps, or the tag params are spread over several lines (see FAQ).
  • A setting from Edit map settings is ignored on the front-end: a tag param wins, see Rendering the field in a template.
  • Imported data doesn't show or breaks the CP map: the data doesn't follow the structure above (e.g. a popup without the base64: prefix, or missing circles, rectangles or map.center).