geoMap

This component requires the commercial Maps add-on.
LIVE DEMO

geoMap displays geographical data.

XML Element

geoMap

Java Class

GeoMap

Basics

Declare the maps namespace in the view’s XML descriptor:

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:maps="http://jmix.io/schema/maps/ui"
      title="msg://mapBasicView.title">

Studio adds the namespace automatically when you add the component using the Add Component action in the top actions panel. See Component Palette.

Then add the geoMap element:

<maps:geoMap id="map"
             height="100%"
             width="100%"/>

With the id attribute set, inject the GeoMap component into the controller to access its API directly:

@ViewComponent
private GeoMap geoMap;

@Subscribe
public void onInit(final InitEvent event) {
    geoMap.addLayer(new TileLayer()
            .withSource(new OsmSource()
                    .withUrl("https://tile.openstreetmap.org/{z}/{x}/{y}.png")
                    .withOpaque(true)
                    .withMaxZoom(10)));
}

Layer

The GeoMap component can include multiple layers that display different types of geographic information. Initially, the map does not have layers.

The Maps add-on provides the following layer types:

  • TileLayer displays pre-rendered tiled images organized by zoom levels.

  • ImageLayer displays static images or images obtained from a Web Map Service (WMS).

  • VectorLayer displays features and geometries.

  • HeatmapLayer renders point features as a heatmap.

See Layers and Sources for the sources supported by each layer type and usage examples.

You can inject a layer into the controller and interact with it programmatically by accessing its methods directly:

@ViewComponent("map.tile")
private TileLayer mapTile;

@Subscribe
public void onInit(final InitEvent event) {
    mapTile.setSource(new XyzSource()
            .withUrl("https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}"));
}

Source

A source represents the data used to render map layers on the map component. Sources provide the spatial information that defines the content and appearance of the map layers.

The Maps add-on provides the following source types:

See Layers and Sources for source descriptions and usage examples.

The following example defines an OsmSource for a tile layer:

<maps:layers>
    <maps:tile>
        <maps:osmSource attributions="© Your Attribution Info"
                        maxZoom="34"/>
    </maps:tile>
</maps:layers>

You can inject a source into the controller and interact with it programmatically by accessing its methods directly:

@ViewComponent("map.tile.osmSource")
private OsmSource osmSource;

@Subscribe
public void onInit(final InitEvent event) {
    osmSource.withUrl("https://tile.openstreetmap.org/{z}/{x}/{y}.png")
            .withMaxZoom(12)
            .withWrapX(false);
}

View

View defines how the map is displayed in terms of its center, zoom level, rotation, and projection. It essentially sets the initial state of the map when it is loaded in the user interface.

By default, the geoMap component displays a world map with an initial geographical center at (0,0).

<maps:mapView centerX="10.872461786203276"
              centerY="48.36928140366503"
              zoom="4.0"/>

You can specify additional parameters:

  • centerX defines latitude of the initial geographical center of the map. It is passed to the org.locationtech.jts.geom.Coordinate object.

  • centerY defines longitude of the initial geographical center of the map. It is passed to the org.locationtech.jts.geom.Coordinate object.

  • maxZoom - sets the maximum zoom level for the view.

  • minZoom - sets a minimum zoom level for the view.

  • projection defines the coordinate reference system (CRS) used to display geographic data on a map. It transforms three-dimensional Earth coordinates onto a two-dimensional plane. Common projections include EPSG:3857 (Web Mercator) and EPSG:4326 (WGS 84). The default projection is EPSG:3857. You can set a custom projection.

  • rotation - sets the rotation for the view in radians (positive rotation clockwise, 0 means North). For more details see setRotation.

  • zoom defines the specific zoom level. The zoom level begins at 0, representing the maximum zoomed-out view, and progressively rises as you zoom in for a closer perspective.

Custom Projection

LIVE DEMO

Follow these steps to configure a custom projection:

  1. Define Projection Bean. Register the projection in your Spring configuration using PROJ.4 format:

    @Bean
public ProjectionRegistration projectionRegistration21781() {
    return new GeoMapProjectionRegistration("EPSG:21781",
            "+proj=somerc +lat_0=46.9524055555556 " +
                    "+lon_0=7.43958333333333 " +
                    "+k_0=1 +x_0=600000 +y_0=200000 +ellps=bessel " +
                    "+towgs84=674.374,15.056,405.346,0,0,0,0 +units=m " +
                    "+no_defs +type=crs");
}

  2. Configure Map Component. Specify the projection attribute for a mapView in your XML descriptor:

    <maps:geoMap id="geoMap"
             width="100%"
             height="100%">
    <maps:mapView projection="EPSG:21781"
                  centerX="10.872461786203276"
                  centerY="48.36928140366503"
                  zoom="4.0">
    </maps:mapView>
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

  3. Initialize in Controller. Apply the projection programmatically to all map components on the page:

    @ViewComponent
private GeoMap geoMap;

@Subscribe
public void onInit(final InitEvent event) {
    geoMap.setProjection(() -> "EPSG:21781");
}
    The projection applies to all map components on the page. Once set, all coordinate operations use the projection’s units (meters, degrees, etc.).

Extent

The extent specifies the geographic boundaries of the map view or a specific layer in terms of coordinates, defining the visible area on the map.

Extent is typically defined by minimum (top-left corner) and maximum (bottom-right corner) coordinate values in the form of [minX, minY, maxX, maxY], representing the bounding box of the area.

Choose a layer or the mapView element in the Jmix UI structure panel or in the view XML descriptor, and then click the Add button in the inspector panel. From the drop-down list, select Extent, and configure the minX, minY, maxX and maxY attributes as indicated below.

<maps:mapView centerY="51.0"
              centerX="40.0"
              zoom="4.0">
    <maps:extent minX="-15.0"
                 minY="30.0"
                 maxX="40.0"
                 maxY="60.0"/>
</maps:mapView>

Extent Constraint Options

By default, when mapView has an extent, OpenLayers constrains the whole viewport to stay inside this extent. In responsive layouts, this can force the map to zoom in when the map container aspect ratio differs from the extent aspect ratio.

Use the following mapView attributes to adjust this behavior:

  • showFullExtent - allows zooming out far enough to show the whole configured extent, even when the container’s aspect ratio differs from it. The default value is false.

  • constrainOnlyCenter - applies the extent constraint only to the view center, so viewport edges may move outside the extent. The default value is false.

  • smoothExtentConstraint - applies the extent constraint smoothly, allowing slight overscroll with an ease-back effect instead of a hard stop. The default value is true.

These attributes are creation-time options. They are passed to the OpenLayers view during initialization and cannot be changed at runtime.

<maps:geoMap id="map"
             width="100%"
             height="340px">
    <maps:mapView centerX="7"
                  centerY="7"
                  zoom="7"
                  showFullExtent="true">
        <maps:extent minX="5"
                     minY="0"
                     maxX="20"
                     maxY="15"/>
    </maps:mapView>
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

Attributes

geoMap does not define component-specific attributes.

The following shared attributes are supported by geoMap:

id - alignSelf - classNames - colspan - css - height - maxHeight - maxWidth - minHeight - minWidth - visible - width

Handlers

The following events are specific to geoMap:

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).
Name Description

MapClickEvent

Fired for a map click. A double-click causes this event to be fired twice.

MapDoubleClickEvent

Fired when the user double-clicks the map.

MapMoveEndEvent

Fired after the map view finishes moving.

MapSingleClickEvent

Fired for a single click after the component determines that the interaction is not a double-click.

MapZoomChangedEvent

Fired when the map zoom level changes.

The following shared handlers are supported by geoMap:

AttachEvent - DetachEvent

Elements

A geoMap can include one mapView element and a required layers element. The layers element can contain tile, image, vector, and heatmap layers, each with the source and styling elements supported by its layer type.

See Also