Add a Map Field to your form by clicking the icon of a map pin and then selecting either Map Single or Map Multiple.
Map Single
A Map Single allows a single pin to be dropped. You can:
Allow the user to select a point by dropping a map pin.
Select a default point to be dropped as a map pin by using latitude and longitude coordinates in the default value.
These could be hardcoded (e.g. 51.5, 0.12) or tokenised (e.g. {selected_point}). This enables a pin to be dropped on a map after an address is selected from an LLPG lookup. For more information, please see the ‘Getting Data Into the Map Field’ section below.
Select the user's location as a map pin by enabling Request user location data in Form Settings and leaving the default value blank. When enabled, users are prompted to consent to share their location. After they consent, the map zooms to their general area.
To drop the pin, either click the map at the desired point or click the Show me where I am icon to place the pin at your current location.
A pin always displays the address when clicked on. It can also display information in the information bubble, which is explained below.
Map Multiple
A Map Multiple allows multiple pins to be dropped. Please note that, unlike a Map Single, the map cannot be blank when the form is loaded. Pins must be pre-populated on the map, after which you can configure your field to allow a user to select their own point, if you want.
The list of pins can be rendered on the Map Multiple by:
List of Points Field
i.e. entering a static list of points to render, hardcoded into the list of points field of the Map Multiple field in the format 'lat', 'lng' with a carriage return to separate the multiple points.
If listing points this way, a default point can be set by selecting it from the drop-down list in 'Default Value' - and this will be marked with a blue pin. The other points will be shown with green pins and any points added by the form filler will be marked with red pins.
Lookup
i.e. attaching a lookup created in the Integrations Manager which returns columns called 'lat', 'lng', 'name' and 'display'. The lookup can also return columns called 'mapIconSelected' and 'mapIconUnselected' to use custom icons for the markers.
A default point can be defined - and this will be marked with a blue pin, the other points will be shown with green pins. Any points added by the form filler will be marked with red pins.
Fields
Field Name
Description
Example
Required
display
unique identifier for each pin location
uu60171307
No
name
Bubble text contents when clicking on the pin
46km NE of Old Faithful Geyser
No
lat
Latitude co-ordinates
44.8036667
Yes
lng
Longitude co-ordinates
-110.487
Yes
mapIconSelected
replaces the default "selected" pin with a pin icon of your choosing
No
mapIconUnselected
replaced the default "Unselected" pin with a pin icon of your choosing
No
To use the columns 'mapIconSelected' and 'mapIconUnselected', you will need to create the relevant icons as suitable image to be stored in a publicly available, web-based location such as the Amazon S3 store, and then reference these images by their URL in your lookup
Please note that a pin always displays the address when clicked on. It can also display information in the information bubble, which is explained below.
Basic Map Customisation
Initial View Centre
The initial view centre is available for Map Single and Map Multiple and is used to centre the map without a map pin. It can contain a token, but the value should be in the format 'lat,lng'.
Zoom Level
The Zoom Level is available for Map Single only. The Zoom level is based on mercurial maps, so 1 is the highest level and 100 the lowest. In Multiple Maps this is not configurable, the zoom level will be adjusted within the form to display the map pins automatically.
Information Bubbles
You can add custom text to the information that appears when clicking on a map pin by using the 'Information Bubble' field in Advanced Settings.
Information Bubbles can be customised in the Advanced Settings for Map Single only. For Map Multiple, you can populate the information bubble by returning what you want to be shown as the column 'name'.
Map Tile Service
You can change the service used to render the maps witOh the 'Map Tile Service' setting in Advanced Settings. For example, you could change the map type to ESRI or Google. You can also set a custom map tile service by selecting 'Custom Tile Layer...', which is explained in our Custom Layer guide here.
Other options you may wish to use include:
Static Map - Helps maps to format in Printable Integrations, as explained below.
Hide When Blank - Hides the map if nothing was selected.
Show Controls - Unticking this will hide the search and pin tools from the map. It will not hide the zoom control, which must be retained for accessibility purposes.
The British Geological Survey provide a free webservice that can be used to convert the lat/lng data returned from map fields into nothing & eastings for consumption by third party services
Getting Data Out of the Map Field
When a user has selected a point on a map, it is useful to be able to use the data from the pin in other form fields. For example, you may want to display the nearest address to the pin back to the user, or use it in later stages of the process.
To pull the map pin's data, you can use any of the following tokens in the default value of a text field in your form.
Please note when adding these tokens replace 'Map' with the default value of your map field. For example, if the default value of your map field is 'mapsingle1' then your token should be {mapsingle1:street}.
Map Tokens
{Map:lat} - Displays latitude coordinates
{Map:lng} – Displays longitude coordinates
{Map:street} – Displays street name
{Map:town} - Displays town
{Map:region} – Displays region
{Map:country} – Displays country
{Map:postcode} – Displays postcode
{Map:address} – Displays full address
{Map:name} - Displays whatever you returned as 'name' if if the pin has been generated by List Source > Lookup.
{Map:display} - Displays whatever you returned as 'display' if if the pin has been generated by List Source > Lookup.
{Map:NameOfYourColumn} - displays the value of another column attached to the pin if the pin has been generated by List Source > Lookup.
Getting Data Into the Map Field
It is possible to feed data from the form into a Map Single Field. For example, you can feed an address selected via a postcode autolookup into the map, where it will be marked with a pin.
You will need:
a field where the user will enter their postcode;and
a select field with a lookup on it which returns the addresses for the postcode.
When the user selects the address, you can return the address's lat & lng into a hidden field in the correct format. At this point, the hidden field can be used as the defaiult value of the map field.
Using Maps in Integrations
Using the tokens listed above allows you to retrieve the data from the map and then use the text values in your integrations. The only case where a map may need to be printed visually in an integration is in Printable Integrations or Email Integrations. However, there are limitations to using these, especially if you use custom base layers.
The only map type that works in a Printable Integration is Google Maps. This needs to be set as the map's 'Map Tile Service' in the field's Advanced Settings.
In the Advanced Settings, Static Map needs to be checked. If you don't want the map to be static in the form, you need two maps fields. The first map field will have your normal settings, with the second map field set to static and hidden (hide using outer class or display condition). Then the values will be passed from the first map to the second via a default value.
To print the map, use its dataname as a token in your integration (e.g. {issueMap}).
If your map is not formatting correctly, you can try one of the following solutions, bearing in mind that since Google have changed their APIs you may be required to purchase the API key from them):
Use HTML:
Include an image tag (ie. <img src="yourURL">) in the email to load a static map. You can use http://staticmapmaker.com/ to figure out the HTML content for the size and style of map you want, supplying the location in the format 'lat,lng'. You can then substitute the token from the map field into this.
Use JavaScript:
Using HTML works well for most situations, but it can pose limitations if you are working with custom base layers. Furthermore, it assumes the user will have an internet connection in order to download the map image at the time of viewing. Using Javascript is a more complex solution, but it is also more robust: Javascript can be added to the form to copy the images from the map into a HTML5 canvas, then convert the canvas to a PNG image data URL which you can store in a text field on the form. This can then be included in emails and printables with minimal fuss.
When returning the address from an Open Street Map, the result is not always accurate.
Reserved tokens - the token name {location} is a reserved token used within the product, it should therefore not be used as a input field unless you are intending to use the token itself. Using reserved tokens will mean default values maybe imported from the token.
There is a known issue that occurs that results in some set points on a map being positioned randomly rather than in their expected position. This is caused by rows in a database having no values for the 'lat' and 'lng' attributes (which are columns in the database). A lookup cannot return rows that do not have an actual value for 'lat' or 'lng'.
Map data is not stored in the data dump. To get this data, you must add text fields to your form, with the relevant token as explained above.
The map search function will close if you attempt to scroll on the map.
If using Google Maps on some mobile devices the map does not always resize making it difficult to view
The tokens that include colons will not work in integrations as a direct token eg {map:address} but if you use them as a default value in a helper field, and then use the helper field in your email integration etc this will work as expected.
Calculated defaults don't work for a map on the same section. Same for centre and zoom. If calculating map centre etc - and using token to pass into a map the map will need to be on a later section
