Skip to main content

Map

The Map ViewTemplate provides an interactive map component within the ADITO client. It enables the visualization of geospatial data and supports various types of overlays such as markers, radii, polylines, and polygons. The map is rendered based on tile data provided by a configurable map server.

Overview​

This ViewTemplate integrates with external tile-based mapping services to present location-based information, enhanced by zoom controls and interactive overlays.

Supported Map Elements​

  • Markers: Represent point-based positions using geodetic coordinates (LON/LAT). For example, company locations based on addresses.
  • Radius Around a Point: Used for visualizing a range search, such as displaying all companies within a specified radius around a central location.
  • Polylines and Polygons: Useful for visualizing boundaries or distribution areas, with optional interactive behavior.
info

Example:
ViewTemplate "OrganisationMap" within the OrganisationFilter_view. The following paragraphs refer to this example ViewTemplate.

Client Integration​

In the ADITO client:

  • Navigate to Contact Management > Company
  • In the FilterView, select the "Map" ViewTemplate, using the View selection button
  • The map displays either all available companies or only those matching a set filter
  • The maximum number of displayed locations is configurable

Map

Users typically filter companies in the "Table" ViewTemplate first and then switch to the "Map" ViewTemplate to visualize the result.

Configuration​

Prerequisite: Coordinate Data​

The standard address of each company must include valid geolocation values:

Field in Organisation_entitySource
STANDARD_LON (longitude)References LON in Address_entity
STANDARD_LAT (latitude)References LAT in Address_entity

These values must be present in the ADDRESS table columns LON and LAT.

When a new ADDRESS dataset is created in the client, the coordinates are automatically generated by the following logic:

new LocationFinder().getGeoLocation(address)

This function is implemented in the Location_lib library and uses the Nominatim API for geocoding.

note

This feature is only active if the property nominatim.enable is set to true and the Nominatim server is properly configured under
Projects window > preferences > PREFERENCES_PROJECT > Custom > PREFERENCES_PROJECT > nominatim.xxx

Post-import Coordinate Assignment​

If address datasets are imported without coordinates:

  • Execute "Set missing address locations" in Context "Process" of the ADITO Manager.
    → Server process: setMissingAddressLocations_serverProcess

To overwrite and update coordinates for all datasets:

  • Execute "Set all address locations".
    → Server process: updateAllAddressLocations_serverProcess

Both processes originate in the project folder process > executables.

Map Configuration Properties​

Configuration is controlled via specific properties, which are documented in the "Properties" window.

Notable Properties​

configField​

Specifies the EntityField that provides map configuration in JSON format.
Example: MAP_CONFIG in Organisation_entity, filled via valueProcess using functions from MapViewTemplate_lib.

Example logging for debugging:

logging.log("MAP_CONFIG: " + res);

autoGeneratedMarkerLatitudeField / ...LongitudeField​

Define which fields supply the geographic coordinates of the markers.

maxDBRow​

Limits the number of records (e.g., company addresses) shown on the map.

autoGeneratedMarkerColorField​

Defines the marker color using a string (e.g., "priority-high-color") or a JDito constant (e.g., neon.PRIORITY_HIGH_COLOR).

geoJsonFeatureCollectionField​

Holds a GeoJSON FeatureCollection for adding custom map elements.

  • Example data source: MAP_FEATURE_COLLECTION
  • Typically generated from MapViewAdditionalFeatures_param
  • Used in actions like "Radius Search"

Custom Marker Icons​

You can define custom icons using:

  • Icon names: e.g., "VAADIN:FACTORY"
  • Base64-encoded images (disables autoGeneratedMarkerColorField)

Example: Adding Interactive Radius with Drill-Down​

var homeFeatureCollection = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "ADITO-radius": vars.get("$field.SearchRadius") * 1000,
        "ADITO-color": neon.PRIORITY_HIGH_COLOR,
        "ADITO-icon": "VAADIN:MAP_MARKER",
        "ADITO-targetContext": "Organisation",
        "ADITO-targetId": vars.get("$param.OriginUid_param"),
        "ADITO-label": ContextUtils.loadContentTitle("Organisation_entity", vars.get("$param.OriginUid_param"))
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          parseFloat(vars.get("$param.LocationLon_param"), 10),
          parseFloat(vars.get("$param.LocationLat_param"), 10)
        ]
      }
    }
  ]
};

Action: openAroundLocation (Organisation_entity) Opens View: AroundOrganisationLocation_view (Context: AroundLocation)

MapTiler Integration​

Setup​

  1. Obtain a MapTiler license key
    → https://www.maptiler.com/cloud/plans
  2. Configure property geo.maptiler.apikey
    → system > default > _____CONFIGURATION > Custom > _____CONFIGURATION > geo.maptiler.apikey
  3. Save
  4. Restart the ADITO server
  5. Open "OrganisationMap" in OrganisationFilter_view to validate

To reuse this in other contexts, replicate the relevant EntityFields and configuration.

Map Server Requirements​

The ViewTemplate supports any Leaflet-compatible tile server.
Tiles are image-based (not vector), and map data is segmented into square tiles.

note

The ViewTemplate uses the Leaflet library: https://leafletjs.com
General tile system reference: OpenStreetMap Tile Usage

Requirements for Tile Server​

  • Serves raster tiles (images)
  • Uses EPSG3857 coordinate system
  • URL format: "xyz" → includes {z} (zoom), {x}, and {y}
  • Authentication via URL parameter (e.g., apikey, appid)

configField Example​

{
  "startingCenterPosition": {
    "lat": 50.989791,
    "lon": 4.772377,
    "autoLocate": true,
    "zoomLevel": 5
  },
  "boundaries": {
    "minZoom": 1,
    "maxZoom": 20
  },
  "tiles": [
    {
      "title": "Streetmap",
      "url": "https://api.maptiler.com/maps/streets/256/{z}/{x}/{y}.png?key=rf1XkCIjY4iUR4sACNjT",
      "attribution": "<a href='https://www.maptiler.com/copyright/' target='_blank'>&copy; MapTiler</a> <a href='https://www.openstreetmap.org/copyright' target='_blank'>&copy; OpenStreetMap contributors</a>"
    }
  ]
}

URL Placeholders (Leaflet)​

PlaceholderDescription
{s}Subdomain (e.g., a, b, c)
{z}Zoom level
{x}Tile X coordinate
{y}Tile Y coordinate
{r}Retina support (@2x tiles)

Example Authenticated Tile URL​

https://www.{s}mymapsupplier.org/{x}/{y}/{z}.png?apikey=MYAPIKEY&lang=DE&style=flat
warning

Since tile requests are made using standard <img> tags, OAuth authentication is not supported.
Any URL used — including the API key — can be inspected in browser developer tools.

Runtime Flexibility​

Map configurations can be changed at runtime. Users can switch tile providers or styles simply by updating the JSON in the configField. New settings apply upon view reload.

note

Configuration interfaces may change in future ADITO versions.