Learn

Location

Do some amazing things with coordinates, distances, and maps.

For information on how to place maps into your templates, see the location tag.

Connect your entries to points on a map with location. Using location will let you do some amazing things with coordinates, distances, and maps.

First things first, you’ll want to let people connect entries to a spot on a map. This is where the fieldtype comes in.

Configuration

This add-on comes with a bunch of configurable settings to control how the fieldtype works in your Control Panel. All of these options are settable in the add-on’s configuration file, and then can be individually overwritten in your fieldsets per location-field.

Default Map Look

Set the starting latitude, longitude, and zoom with the starting_ options:

starting_latitude: 44.33
starting_logitude: -68.21
starting_zoom: 16

Define the highest and lowest levels of zoom the user can use in the map view:

min_zoom: 4
max_zoom: 18

Determine how precise you want the latitude and longitude fields to be when showing decimal points, the higher then number, the more precise:

float_precision: 5

Geolocation

Users will be presented with the option to locate them if their device and browser supports geolocation (if a user’s set-up can’t do geolocation, the link won’t show up). You can enable or disable this feature all together with:

allow_geolocation: true/false

You can also set a default zoom-level for when a user is geolocated:

geolocation_zoom: 17

We’ve optionally given you the ability to use a FourSquare API key to automatically populate the name field of the nearest venue when a user geolocates. We’ve included our sample development key as an example, but you’ll want to grab your own from FourSquare (they’re free) if you want to use this feature.

To turn on FourSquare look-up, set use_foursquare to true and put in your client_id and client_secret:

use_foursquare: true/false
foursquare_client_id: AAAAAAAAAA  # get this from FourSquare
foursquare_client_secret: BBBBBBBBB  # also get this from FourSquare

You can also define the maximum radius around the user’s current coordinates for FourSquare to look for a venue. Do so with this value (in meters):

foursquare_radius: 200

Map Interaction

The maps we’re using come with a number of ways that users can interact with them, but they’re not always going to be what you want. You can set those options with the interaction setting:

interaction_scroll_wheel_zoom: true/false
interaction_double_click_zoom: true/false
interaction_box_zoom: true/false
interaction_touch_zoom: true/false
interaction_draggable: true/false
interaction_tap: true/false  # as of v 1.7.5

Use interaction_scroll_wheel_zoom to let users scroll with their mouse’s wheel (or a track-pad gesture). Use interaction_double_click_zoom to let users double-click to zoom in. Use interaction_box_zoom to let users hold shift on their keyboards while drawing a box in the map of where they wish to zoom to. Use interaction_touch_zoom to let users pinch-zoom on touch devices. Use interaction_draggable to let users pan the map.

As of v1.7.5, you can also use interaction_tap to enable or disable touch events on the map. This is true by default, and pairs well with interaction_dragging.

Map Style

Starting with v1.7, you can connect to a number of different popular mapping services (some free, others not) right out-of-the-box. The old CloudMade-specific variables have been replaced with generic mapping-service variables that let you choose a number of different map types.

There are four variables that can be set:

  • mapping_service is the name of the service to use, see below for a full list of available options
  • mapping_service_api_key is the key used to access this service, not always required
  • mapping_service_style is a style parameter that some services use to let you select how your map looks
  • mapping_service_attribution is a way to override the default built-in attributions for each map; note that the values built in are the ones recommended by each mapping_service (respectively), altering these attributions may be against the license of the service you choose, use caution when changing these

Since each service is a little different, here is a full list of how to use them all:

OpenStreetMap (The New Default)

We’ve switched our default mapping service to be OpenStreetMap because they’re free to use and are actually very high quality maps. To use OpenStreetMap, use the following settings:

mapping_service: openstreetmap
mapping_service_api_key: 
mapping_service_style: 
mapping_service_attribution:

OpenCycleMap

OpenCycleMap is another free option that provides a lot of great maps with bike trails. To use OpenCycleMap, use the following settings:

mapping_service: opencyclemap
mapping_service_api_key: 
mapping_service_style: 
mapping_service_attribution:

MapBox

Statamic now supports MapBox, who make absolutely stunning maps that are completely customizable. To use MapBox, use the following settings:

mapping_service: mapbox
mapping_service_api_key: examples.map-zr0njcqy  # enter the "Map ID" that you'd like to use
mapping_service_style: 
mapping_service_attribution:

CloudMade

Of course, we still support CloudMade maps. To use CloudMade, use the following settings:

mapping_service: cloudmade
mapping_service_api_key: awefua0w9ega7232  # enter your API key
mapping_service_style: 997  # enter the tile style ID that you'd like to use, 997 is a good default 
mapping_service_attribution:

MapQuest

MapQuest provides free maps for use on your site as well. To use MapQuest, use the following settings:

mapping_service: mapquest
mapping_service_api_key: aw0982039j2g3  # enter in your MapQuest API key
mapping_service_style: map  # two options available here, `map` will be a rendered map, `sat` will be aerial photography
mapping_service_attribution:

Stamen

Stamen maps are interesting and beautiful map tiles for use on your site. To use Stamen maps, use the following settings:

mapping_service: stamen
mapping_service_api_key: 
mapping_service_style: toner  # choose the style name that you want to use (toner|terrain|watercolor etc.)
mapping_service_attribution:

LeafletJS comes with a mode that will detect high-density displays and will serve the next-zoomed-in-level at 50% the size to hopefully make things high-res. This has admittedly mixed results, but we wanted to provide the option and let you decide:

detect_retina: true/false

Common Places

You can create a list of common places that users can choose from in addition to picking a location on a map. This pop-up will be helpful if you have a set list of locations that you want to use over and over again, either as an end point or as a starting point for a draggable map marker.

Create a list of places in your configuration like so:

common_locations:
  -
    name: Acadia National Park
    latitude: 44.33
    longitude: -68.21
    zoom: 12
  -
    name: Badlands National Park
    latitude: 43.75
    longitude: -102.50
    zoom: 12
  -
    name: Denali National Park
    latitude: 63.33
    longitude: -150.5
    zoom: 12

Don’t set any common_locations if you don’t want the link to show up.

Using Locations in Listings

Statamic’s core {{ entries:listing }} tag has been update to play with the new features of location.

Enabling Location

In addition to saving location information with a location fieldtype, you’ll also need to inform the listing tag that you want to use location features. To do this, set the locate_with parameter to the field that contains each entry’s location information. For example, if you named your location field spot, you would do this:

{{ entries:listing folder="stores" locate_with="spot" }}

{{ /entries:listing }}

This listing tag now is ready to do things with that location information. Entries that have the spot field will now have access to a couple of extra tags within the tag pair:

  • latitude is the entry’s latitude
  • longitude is the entry’s longitude
  • coordinates is the entry’s latitude and longitude as comma-sepearted coordinates

With {{ coordinates }}, you can use the variable modifiers distance_in_mi_from and distance_in_km_from. These modifiers take one parameter, another location, and will return the distance between your entry and the coordinate given in the format that you ask for. Note: make sure there is no space in your cooridinates.

{{ entries:listing folder="stores" locate_with="spot" }}
   {{ title }}, 
   {{ coordinates|distance_in_mi_from:44.33,-68.21 }} mi from basecamp
   <br>
{{ /entries:listing }}

We’ve added some precision modifiers in v1.5 to help you rein in those calculations. You can use floor, ceil, or round (with round you can also optionally specify the precision to use) with your distances. Remember, you can chain modifiers together:

{{ entries:listing folder="stores" locate_with="spot" }}
   {{ title }}, 
   {{ coordinates|distance_in_mi_from:44.33,-68.21|round:2 }} mi from basecamp
   <br>
{{ /entries:listing }}

There’s a second way to get distance information out of an {{ entries:listing }} tag, and that’s with the center_point parameter. Give that a set of coordinates and each entry will do a bit more work for you:

{{ entries:listing folder="stores" locate_with="spot" center_point="44.33,-68.21" }}

{{ /entries:listing }}

In addition to latitude, longitude, and coordinates that the locate_with parameter enabled, you can also use distance_mi and distance_km to get the calculated distance that your entry is from the center_point. As before, you can still use variable modifiers to round those calculations into something more manageable:

{{ entries:listing folder="stores" locate_with="spot" center_point="44.33,-68.21" }}
   {{ title }} is just {{ distance_km|round:1 }}km away.
{{ /entries:listing }}

Further, when specifying both locate_with and center_point, you can sort your entry listings by distance, either from closest-to-farthest or farthest-to-closest:

{{ entries:listing folder="stores" locate_with="spot" center_point="44.33,-68.21" sort_by="distance" sort_dir="asc" }}
   {{ if first }}
      <h2>Closest Stores</h2>
      <ul>
   {{ endif }}

   <li>
      <strong>{{ title }}</strong><br>
      {{ distance_mi|round:2 }}mi away
   </li>

   {{ if last }}
      </ul>
   {{ endif }}
{{ /entries:listing }}

This article was last updated on March 30th, 2016. Find an error? Please let us know!