Cartographer Documentation

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.