Andrew Haine

Cartographer Documentation

Andrew Haine
<<< Back to details

Installation

Once you have a license for the addon, download the addon files from the Marketplace. The 'Cartographer' directory should be placed in you site/addons folder.

You will then need to input your API keys for either Google Maps or Mapbox (or both!). These will need to be copied into the relevant boxes within the addon settings in the control panel.

Plese note: For google maps geocoding to work you will need to enable the Geocoding API on your cloud project, in addition API keys with referrer restrictions are not allowed to make requests to the geocoding API. No extra configuration is required for Mapbox Geocoding!

Usage

Add the Cartographer fieldtype to any of your fieldsets as you would any other field, you may toggle between using Google Maps or Mapbox in the 'Extras' tab when editing the field. The data is standardised on the backend so you may switch between the two at your own leisure.

Additionally, you may set the coordinates of the default center on a per-field basis through the 'Extras' tab, these coordinates will be where the map center is when the map loads before any data has been saved.

A brief overview

Google Maps Mapbox Both
Set center Drag circular icon Drag yellow marker Drag map and hit 'set center'
Markers - - Hit 'add marker' and move into position
Styles Use SnazzyMaps (or another service) and paste the array into the styles box Choose from the predefined styles or create your own and paste the link
Controls - - Check the boxes for the controls you wish to display (under 'Advanced')
Geolocation - - Search for a location and hit Enter

Tags

For the most part you will only require the main {{ cartographer field="my_map" }} tag. This will output a full embedded map - detecting which map library to use. This tag has a number of options that can be passed:

Parameter Type Description
field String The name of the fieldtype field where the data is stored
classes String CSS classes to add to the map element
width String CSS width attribute
height String CSS height attribute
zoom Integer Override the zoom level set in the CP

Parts

If you would like to control the output of the geodata you can use the parts tag which will give you access to each attribute in the map. Example usage of the parts tag is below.

Example

{{ cartographer:parts field="my_field" }}

    {{ center }}
        {{ lat }}
        {{ lng }}
    {{ /center }}

    {{ markers }}
        {{ id }}
        {{ icon or color }}
        {{ label }}

        {{ position }}
            {{ lat }}
            {{ lng }}
        {{ /position }}
    {{ /markers }}

    {{ options }}
        {{ controls | join:, }}
        {{ styles }}
        {{ zoom }}
    {{ /options }}

{{ /cartographer:parts }}

Parts

Name Type Description
api_key String Google maps API key
center Array Location for the map center, contains lat and lng values
id String A generated unique id for the map
mapbox_access_token String Mapbox access token
markers Array containing marker data Each marker in the map, contains the attributes for label, icon and colour (depending on the library used), the position attribute will contain the lat, lng position data
options Array Metadata for the map, including: controls, map_type_id, styles and zoom

Dump

Alternatively use {{ cartographer:dump }} to dump the data in a string.

<<< Back to details