Maps

Last modified: November 19, 2024

Introduction

The Maps widget enables showing locations on maps. It supports the following map providers:

Basic Usage

For the easiest way to get started with a basic map in your application, follow these steps:

  1. Drag the Maps widget onto your page.
  2. Open the widget properties and add a Google Maps access token in General > Configurations > Google Maps API Key.
  3. In the General > Markers properties section, select New for Markers.
  4. Create a new location marker based on either Latitude and longitude or an Address.

If you want to configure more of your map (for example, end-user interactions and styling) or use a different map provider, see the Settings section below.

Settings

Map Provider

By default, the Maps widget will use Google Maps.

To change the map provider, go to the General properties of the map and enable the Advanced > Show advanced setting. This will introduce a new Advanced tab in the setting window. You can now select one of the map providers listed in the Introduction.

Access Token

For all the map providers except OpenStreetMap, you need to have a token in order to view the map. The appropriate tokens can be retrieved via the links to the map types listed in the Introduction.

After obtaining the access token, provide it to the widget in the General > Configurations widget settings. For Google Maps, the Google Maps API Key property should be used, while for the other map providers the API key property should be used.

Current Location

To show the user’s location on the map, enable this in General > Configurations > Show current location marker.

Markers

To enhance the map widget, you can mark locations on the map by providing them in the widget through General > Markers. The following conditions apply:

  • If exactly one location is provided, the map will center to that location
  • If multiple locations are provided, the map will center to a position in which all markers are visible
  • If no location is provided, a default center location of the Mendix offices is provided

There are two ways to specify locations to be marked, either Based on latitude and longitude or Based on address. Providing either of these is also the only requirement for creating a marker.

You can customize each individual marker in the following ways:

  • You can provide each marker with a title that will be displayed in a pop-up window when the marker is clicked via the Location > Title setting
  • You can customize the icon of the location marker via the individual marker’s setting in Visualization > Marker style (setting it to Image allows you to customize it with either a static resource or dynamic entity)
  • You can attach an event handler to the marker to trigger when an end-user clicks it via the Events > On click setting

To make the process of marking batches of locations easier, it is also possible to specify entire lists of markers at once. You can do this through the General > Markers > Marker list setting, which requires a data source. All the usual Mendix data-source settings apply here, as well as the same marker requirements and customizability as the individual markers.

Controls

Under the Controls properties tab, you can adjust the following settings related to how an end-user interacts with the map:

  • Drag – when enabled, the map will move along when dragging the map
  • Scroll to zoom – when enabled, the end-user can change the zoom level of the map by mouse-scrolling on a desktop machine or using pinch gestures on mobile
    • Note that when using the Google Maps provider, this setting requires the Drag setting to be enabled in order to work
  • Zoom – when enabled, additional control buttons are shown on the map
  • Attribution – when enabled, attributions (credits) are shown at the bottom of the map

If you are using the Google Maps provider, these additional controls are available:

  • Street view – when enabled, there is a button available in the lower-right corner of the map to view the map in Google’s Street View mode
  • Map type – when enabled, there are control buttons in the upper-left corner of the map to change the type of the map
    • The available options are Map, with or without a Terrain layer, and Satellite, with or without a Labels layer
    • By default, this is set to Map without the Terrain layer
  • Full screen – when enabled, there is a button available in the upper-right corner of the map to view the map in full screen

Dimensions

Under the Dimensions properties tab, you can adjust the following settings that are related to dimensional aspects:

  • Width unit and Width – the width of the widget in relation to the rest of the elements on the page
    • The available Width unit options are Percentage and Pixels
    • The Width can be set as an appropriate CSS value
    • These two properties need to be used together to work
  • Height unit and Height – the height of the widget in relation to the rest of the elements on the page
    • The available Height unit options Percentage of width, Pixels, and Percentage of parent
    • The Height can be set as an appropriate CSS value
    • These two properties need to be used together to work
  • Zoom level – the starting zoom level of the map
    • The available options are: Automatic, World, Continent, City, Street, and Buildings
    • Note that when using this setting with multiple marked locations, the level of zoom chosen here will be applied after the map has centered to a position in which all markers are visible

Strict CSP Compatibility

This widget is not yet fully compliant with strict content security policy (CSP). If used with strict CSP, it will result in CSP errors in the console and potentially broken flows in the widget.

Please refer to the Maps CSP guide for more detail.

Widgets Below Version 2.0.0

The Maps widget enables showing locations on maps. These are the available map types:

Features:

  • Show a location on a map based on coordinates
  • Show a list of coordinates on the map
  • Support for multiple data sources
  • Support actions when a marker is clicked:
    • Open a page
    • Call a microflow or nanoflow
  • Customize the display of the marker – if the marker cannot be found from the custom markers, the widget uses the specified custom markers; otherwise, it uses the widget-bundled marker

Limitations:

  • Addresses are not supported
  • Context and static data sources are offline-capable with Mendix data, but you still need to be online to view the map
  • For all map types except OpenStreetMap, you need to have a token in order to view the map – you can get the tokens via the links to the map types listed above
  • Google maps uses Google Maps API v3, so the limitations from Google Premium Plan Usage Rates and Limits apply

Locations are displayed based on coordinates. If there is one location, the map will center to that location. If there are multiple locations, the map will center to a position in which all markers are visible. If no location is available, a default center location of the Mendix offices is provided (in case default center coordinates are not specified).

If auto-zoom is enabled, the map uses bounds zoom; otherwise, it uses the custom zoom level specified. The minimum zoom level is 2, and the maximum is 20.

To add a basic map to your application, follow these steps:

  1. On the Map properties tab, select New for Locations.
  2. On the Data source tab of the Edit Locations Item dialog box, select Context for Data source.
  3. Set the Locations entity, Latitude attribute, and Longitude attribute.
  4. On the Markers tab of the Edit Locations Item dialog box, you can configure a marker icon:
    • Default – displays the widget-bundled marker
    • Static – upload a static Image (for best results, use a PNG file at 32px width and 32px height where the bottom pin is at the center of the image)
    • System image – add a System image path that is a reference to the locations entity (the entity selected should inherit from System.Image, because an error will be displayed otherwise); upload an image into the database to view the system image marker at runtime
    • Marker list – add an enumeration containing the name and caption of the markers to your app and assign that enumeration to the locations entity; then, on the Marker image list tab back on the Edit Maps dialog box, click New for Images to specify the enumeration key Value and the Image
  5. Back on the Map properties tab, select a Map provider.
  6. Fill in the Access token field according to the following scenarios;
    • For Mapbox and Google Maps, add an access token
    • For HERE maps, add an app ID and app code