Addons by Reinos

Appearance

How it works ​

Maps Fieldtype adds a field in which editors draw a map per entry: markers, polylines, polygons, circles and rectangles, plus some map settings. It is an extension of the Maps module: 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. The add-on currently writes nothing to its log; problems show up in the browser console instead.

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), otherwise the map breaks when the entry is opened in the CP. See Webservice for an example.

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.

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. From the entry only these are used: the tiles, the zoom, the center and an enabled scroll wheel, zoom control and scale control. The max zoom, the zoom control position, the scale control position and the overlay are saved but not used on the front-end, and a disabled scroll wheel, zoom control or scale control shows up as enabled. Use the tag params for those.
  • A double quote in a tooltip or popup can break the map. Use single quotes for HTML attributes in a popup.
  • 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, Maps Route and Maps Locator ​

  • Maps (required, 4.x or higher): see Installation. 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 Developer mode (shows errors while the CP map loads).
  • Maps Route: 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 Fieldtype field with DataGrab.

Grid, Channel Form and other modules ​

See Supported modules.

  • The field can be used in channel fields, Grid and Bloqs, and in Low Variables and Content Elements. It can not be added to a Fluid field.
  • 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 the primary role (member group before EE 6) of the member. 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 adds the global variable {reinos_maps_fieldtype_action_url}.
  • It needs Maps to be installed and up to date: without Maps the field can't be shown in the CP.
  • When it is installed over version 2.x (the old Maps Fieldtype), the old add-on is replaced and its fields and data are kept. 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 (enable Developer mode in Maps to see it). 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. The default folder (themes/user/reinos_maps_fieldtype/images/markers/) is not shipped with the add-on; upload your icons there or change Icon dir and Icon url ({base_path} is replaced by the base_path config item, {base_url} by the site_url). 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: see Rendering the field in a template; set it with a tag param.
  • A broken popup or map on the front-end: a double quote in a tooltip or popup.
  • 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).