1. Overview

The add-on gives you an easy way to enrich your application with visual representation and intuitive manipulation for spatial data. With this add-on you are free to use a preferable map provider that meets your needs as it is compatible with the Web Map Service protocol as well as XYZ tiles services.

The component integrates spatial types (point, polyline, polygon) from JTS Topology Suite (JTS) — the most popular Java library for working with spatial data. The add-on provides all the required features to build a comprehensive geographical information system on CUBA.

The add-on supports the traditional multi-layer structure, so it gives full freedom to create well-structured maps of any content.

Key features:

  • Introduces a visual component for Generic UI with rich and clear API.

  • Supports drawing and interactive editing of geo-entities — entities with geometry attributes.

  • Compatible with the Web Map Service protocol as well as XYZ tile services.

  • Provides features for geoanalysis: heatmaps and clustering.

See sample application, using this component.

2. Installation

To install the release version of the component in your project you need to add premium repository and then install the add-on.

2.1. Adding Repository

  1. Open your application in CUBA Studio.

  2. Double-click Properties in the CUBA project tree.

    properties
  3. Click the Plus button in the Repositories section.

    repository
  4. Specify the repository URL:

    and enter your credentials in the corresponding fields. The first part of your license key before dash is the repository user name, the part after dash is the password. For example, if your key is 111111222222-abcdefabcdef, then the user name is 111111222222 (for Bintray repository add @cuba-platform to the user name, for example 111111222222@cuba-platform) and the password is abcdefabcdef. Click OK to save the changes.

    credentials

    Click OK to save the changes.

    Also, you can add the repository by editing build.gradle file. The configuration steps are described in Developer’s Manual.

  5. Select the added repository in the list of repositories to use it in your project.

    properties2
  6. Click OK to save the project properties.

2.2. Adding Component

  1. Double-click Add-ons in the CUBA project tree.

    marketplace
  2. Select Marketplace tab and find Maps add-on.

    maps addon
  3. Click Install button and confirm that you have a subscription in the appeared dialog.

    subscription
  4. Click Apply & Close button and then Continue in the dialog.

    continue

Maps add-on will be installed in your project.

3. Components Compatibility

If your project uses Charts and Maps add-on (or other add-ons providing their own widgetsets), you should add web-toolkit module in your project. It is needed to integrate widgetsets from all used add-ons.

web toolkit

4. Usage

The add-on supports the traditional multi-layer structure commonly used in professional GIS systems. To operate with maps you need to add a visual component — GeoMap and one and more layers.

Layers are used as structural units of maps. For example, one layer may be a tiled base map, another layer may contain polygons describing districts, the third layer might consist of geographical points (locations of customers, shops and so on). By combining these layers, you build a complete map.

layers picture

You are able to define the main map parameters along with the layers in the XML descriptor of the component.

4.1. Inserting a Map into a Screen

The com.haulmont.addon.maps.web.gui.components.GeoMap UI component is used to display a map in your application screen.

To add the component, do the followings:

  1. Declare the maps namespace in the root element in the screen XML descriptor:

    xmlns:maps="http://schemas.haulmont.com/maps/0.1/ui-component.xsd"
  2. Declare the component. XML name of the UI component is geoMap. Component declaration example:

    <maps:geoMap id="map"
                 height="100%"
                 width="100%"
                 center="-99.755859, 39.164141"
                 zoom="4"/>
    </maps:geoMap>
  3. Define the basic component properties id, height, width, center, zoom, if necessary where:

    • center — coordinates of the initial geographical center of the map (longitude, latitude).

    • zoom — initial zoom level. The default value is 15.

  4. Add one of raster layers to display a map on the screen. Here is an example of OpenStreetMap tile layer.

    <maps:tile id="tiles"
              tileProvider="maps_OpenStreetMap"/>

XML descriptor can look like this one:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
        caption="Map"
        messagesPack="com.company.mapstest.web"
        xmlns:maps="http://schemas.haulmont.com/maps/0.1/ui-component.xsd">
    <layout>
        <maps:geoMap id="map" height="100%" width="100%" center="-99.755859, 39.164141" zoom="4">
          <maps:tile id="tiles"
                     tileProvider="maps_OpenStreetMap"/>
        </maps:geoMap>
    </layout>
</window>

You can see that OpenStreetMap is added as a tile layout. The screen contains a full-screen map with initial zoom 4.

openstreetmap

Additional configuration of the map and its layers can be performed in the screen controller. You need to add the component declared in the XML descriptor with @Inject annotation:

@Inject
private GeoMap map;

@Subscribe
protected void onBeforeShow(BeforeShowEvent event) {
    map.setCenter(-99.755859D, 39.164141D);
    map.setZoomLevel(4);

    TileLayer tileLayer = new TileLayer();
    tileLayer.setUrl("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png");
    tileLayer.setAttributionString("&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors");
    map.addLayer(tileLayer);
}

See more GeoMap methods and events in Maps API.

4.2. Adding Layers on the Map

Basically, layers are divided into raster and vector layers. Raster layers consist of raster images, while vector layers consist of vector geometries.

The add-on supports the following types of layers:

  • Tile layer is used to display tiles provided by XYZ tiles services.

  • Web Map Service (WMS) layer is used to display tiles from Web Map Service.

  • Vector layer contains geo-objects (entities with geometry attributes).

To add a layer on a map declare the layers element and its configuration in the geoMap element in the XML descriptor. Here is an example of one raster layer and two vector layers.

   <maps:geoMap id="map" height="600px" width="100%">
           <maps:layers selectedLayer="salespersonLayer">
               <maps:tile id="tiles" tileProvider="maps_OpenStreetMap"/>
               <maps:vector id="territoryLayer" dataContainer="territoryDc"/>
               <maps:vector id="salespersonLayer" dataContainer="salespersonDc" editable="true"/>
           </maps:layers>
   </maps:geoMap>

selectedLayer is a layer which the map is focused on. Selected layer fires events, reacts on user clicks and can be modified by UI interaction in case the layer is editable.

Parameters are common for every type of layers:

  • id — required parameter, specifies the id of the layer.

  • visible — whether the layer is visible.

  • minZoom — minimum zoom level down to which the layer is visible (inclusive).

  • maxZoom — maximum zoom level up to which the layer is visible (inclusive).

Also, you can perform configuration of the layer in the screen controller:

   TileLayer tileLayer = new TileLayer();
   tileLayer.setUrl("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png");
   tileLayer.setAttributionString("&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors");
   map.addLayer(tileLayer);

4.2.1. Adding Raster Layers

Raster layers consist of raster images which is a grid of pixels. Raster layer is usually served as a base background layer of a map. You can download raster images using different providers: tile servers and WMS services.

4.2.1.1. Tile Layer

TileLayer is used to load and display tiles that are served through a web server with URL like http://…​/{z}/{x}/{y}.png. Such tiles are usually referred as XYZ tiles.For example, OpenStreetMap tiles URL pattern is: https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png.

To add a tile layer on a map declare it in the XML descriptor:

<maps:tile id="tiles"
              urlPattern="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
              attribution="&#169; &lt;a href=&quot;https://www.openstreetmap.org/copyright&quot;&gt;OpenStreetMap&lt;/a&gt; contributors"/>

id and url parameters are required.

Note that the most tile servers require attribution, which you can set in attribution parameter. In our example the credit ©OpenStreetMap contributors will appear in the lower-right corner.

In order not to clutter the XML descriptors with the URL and attribution strings:

  1. Move tile server settings to a Spring bean implementing com.haulmont.addon.maps.web.gui.components.layer.TileProvider interface.

  2. Specify a bean name in a tileProvider attribute of the tile element.

OpenStreetMap tile provider comes out of the box, so you can use it like this:

<maps:tile id="tiles"
           tileProvider="maps_OpenStreetMap"/>

Additionally you can perform the tile layer in the screen controller using com.haulmont.addon.maps.web.gui.components.layer.TileLayer class:

TileLayer tileLayer = new TileLayer();
   tileLayer.setUrl("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png");
   tileLayer.setAttributionString("&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors");
   map.addLayer(tileLayer);
4.2.1.2. WMS Layer

Various WMS services can be used as a map provider.

WMSTileLayer layer can be declared in the XML descriptor:

<maps:wms id="wms"
          url="http://ows.terrestris.de/osm/service?"
          layers="OSM-WMS"
          format="image/png"/>

id, url and layers are required parameters. Other parameters have default values, which can be redefined.

wms

Also, you can perform a layer in the screen controller using com.haulmont.addon.maps.web.gui.components.layer.WMSTileLayer class:

WMSTileLayer wmsTileLayer = new WMSTileLayer("wms");
wmsTileLayer.setUrl("http://ows.terrestris.de/osm/service?");
wmsTileLayer.setLayers("OSM-WMS");
wmsTileLayer.setFormat("image/png");
map.addLayer(wmsTileLayer);

See more WMSTileLayer methods in Maps API.

4.2.2. Creating Geo-objects

Geo-object is an entity having a property of a geometry type. This property should have one of the geo-specific datatypes that are included in the com.haulmont.addon.maps.gis.datatypes package:

Datatype

Java type

GeoPoint

org.locationtech.jts.geom.Point

GeoPolyline

org.locationtech.jts.geom.LineString

GeoPolygon

org.locationtech.jts.geom.Polygon

To add the property:

  1. Create a new attribute and select a geo-specific datatype from the list.

    geotypes
  2. Add the following annotations:

    • @Geometry — marks that the property is to be used when displaying the geo-object on a map.

      Note: geo-object must have one geometry property, otherwise an exception will be thrown when drawing the layer.

    • @Convert — specifies a JPA converter defining how the datatype will be persisted. JPA converters for the component’s datatypes are included in the package: com.haulmont.addon.maps.gis.converters. The current version of the component includes converters that transform coordinates into the WKT format which consequently persists as a text. While loading from DB this text will be parsed back into the objects.

Here is an example of geo-object Address:

@Entity
public class Address extends StandardEntity {
    ...

    @Column(name = "LOCATION")
    @Geometry
    @MetaProperty(datatype = "GeoPoint")
    @Convert(converter = CubaPointWKTConverter.class)
    protected Point location;

    ...
}

As you can see, Address is a simple entity, one of which properties location is of a org.locationtech.jts.geom.Point type.

4.2.3. Adding Vector Layers

Vector layers help to effectively work with a group of related geo-objects. Vector layers enable simple displaying, interactive editing and drawing geo-objects on a map.

4.2.3.1. VectorLayer Class

VectorLayer is a base layer for displaying your entities on the map. It is a data-aware component acting as a connector between data (geo-objects) and a map.

To bind geo-objects with the layer you need to pass a datacontainer (or datasource in case of using in legacy screens) to the vector layer. This can be declared in the XML descriptor:

<maps:geoMap id="map">
  <maps:layers>
    <maps:vector id="orderLayer" dataContainer="orderDc"/>
  </maps:layers>
</maps:geoMap>

id and dataContainer (dataSource in case of using in legacy screens) are required parameters. Vector layer works with both InstanceContainer and CollectionContainer.

To make the layer editable add the editable parameter:

<maps:geoMap id="map">
  <maps:layers selectedLayer="orderLayer">
    <maps:vector id="orderLayer" dataContainer="orderDc" editable="true"/>
  </maps:layers>
</maps:geoMap>

Additionally you can create VectorLayer in the screen controller:

VectorLayer<Order> orderLayer = new VectorLayer<>("orderLayer", new ContainerVectorLayerItems<>(ordersDc));
map.addLayer(orderLayer);

To determine geometry style for geo-objects use setStyleProvider() method. In CUBA 7.0+ screens you can perform this declaratively using the @Install annotation in the screen controller, for example:

@Install(to = "map.territoryLayer", subject = "styleProvider")
private GeometryStyle territoryLayerStyleProvider(Territory territory) {
        return new PolygonStyle()
               .setFillColor("#08a343")
               .setStrokeColor("#004912")
               .setFillOpacity(0.3)
               .setStrokeWeight(1);
    }

Classes for geometry style are included in the com.haulmont.addon.maps.web.gui.components.layer.style package.

Geo-objects can be selected by user click or automatically from the associated data container.

setSelectedGeoObject() method sets the geo-object which the layer is focused on. For example, if an entity is opened in an editor screen it will be implicitly selected in a corresponding vector layer.

See more VectorLayer methods in Maps API.

4.2.3.2. Clustering

For a vector layer consisting of geo-points it is possible to group nearby points into clusters:

maps clustering

To enable clustering add cluster element inside vector in the XML descriptor:

<maps:vector id="locations" dataContainer="locationsDc" >
  <maps:cluster/>
</maps:vector>

You can specify additional clustering options:

  • radius — maximum radius that a cluster will cover, in pixels (default: 80).

  • weightProperty — if specified, then each point of the layer will have a weight value (int) defined by weight property of a geo-object. This value will be used when calculating the summed up value of the cluster (by default, the number of points is used).

  • showCoverage — show bounds of the cluster when hovering a mouse over it.

  • disableAtZoom — specifies a zoom level from which clustering will be disabled.

  • showSinglePointAsCluster — show single point as a cluster of 1 size.

4.3. Drawing Geometry

Open a screen containing a map with an editable VectorLayer.

To draw a point just click on the map.

point

For drawing a polyline or a polygon specify the firs point and continue clicking on the map. To stop drawing click the last added point.

line

To add a hole inside a polygon right-click and select Add hole. Start drawing a hole inside the poligon.

polygon1

To delete a geometry right-click and select Clear geometry.

4.4. Using Canvas Layer

CanvasLayer is a utility layer belonging to a map by default. This layer is used to draw and display geometries on a map. It is similar to VectorLayer since they both display vector geometries. The difference is that VectorLayer works with geo-objects while CanvasLayer works just with geometries. It makes the task of displaying some geometry on a map really straightforward so there is no need to store data in an entity.

To obtain the canvas layer of a map call map.getCanvas().

Here is an example of adding a geographical point on the canvas layer:

CanvasLayer canvasLayer = map.getCanvas();

Point point = address.getLocation();
canvasLayer.addPoint(point);

Methods that add geometries on a canvas return an object that represents this geometry on the canvas: CanvasLayer.Point, CanvasLayer.Polyline or CanvasLayer.Polygon. Using this object you can define a style or pop-up window, subscribe to events connected with the geometry, or use this object when you want to remove the geometry from the canvas.

Here is an example:

CanvasLayer.Point location = canvasLayer.addPoint(address.getLocation());
location.setStyle(new PointStyle(
        new FontPointIcon(CubaIcon.HOME)
                .setIconPathFillColor("#ff0000")
                .setIconTextFillColor("white")
                .setIconPathStrokeColor("black")))
        .setPopupContent(address.getName())
        .setEditable(true)
        .addModifiedListener(modifiedEvent -> address.setLocation(modifiedEvent.getGeometry()));

You can also draw geometries on the canvas via UI. For example, to draw a point invoke canvas.drawPoint() method. After this method is called the map will turn into the drawing mode. The method accepts Consumer<CanvasLayer.Point> function, in which you can perform additional actions with the drawn point.

canvasLayer.drawPoint(point -> {
    address.setLocation(point.getGeometry());
});

Note that before drawing geometries via UI on the canvas you need to select the canvas on the map by calling map.selectLayerById(CanvasLayer.ID). You can also specify the selected layer in the XML descriptor:

<maps:geoMap id="map" height="600px" width="100%">
        <maps:layers selectedLayer="canvas">
            <maps:tile id="tiles" tileProvider="maps_OpenStreetMap"/>
                ...
        </maps:layers>
</maps:geoMap>

See more CanvasLayer methods and events in Maps API.

4.5. Additional Options

4.5.1. Heatmaps

Heatmaps provide a visual representation of data density across a set of geographical points.

heatmap

GeoMap UI component provides a method for adding a heatmap overlay to a map: addHeatMap(Map<Point, Double> intensityMap), where each entry of the map represents a geo-point and it’s intensity value, which should range between 0 and 1.

You can customize the appearance of a heatmap and change the intensity value range using the overloaded method addHeatMap(Map<Point, Double> intensityMap, HeatMapOptions heatMapOptions).

Class HeatMapOptions contains various options for a heatmap:

  • maximumIntensity — the maximum point intensity (default: 1).

  • blur — the amount of blur in a point (default: 15).

  • radius — the radius of each point of a heatmap in pixels (default: 25).

  • gradient — the color gradient config defined by a map of pairs [intensityValue : rgbColor]. For example, [0.4: 'blue', 0.65: 'lime', 1: 'red'].

  • minOpacity — the minimum opacity the heat will start at (default: 0.05).

  • maxZoom — the zoom level where the points reach maximum intensity (as intensity scales with zoom). By default, equals the maxZoom of a map.

4.5.2. Pop-up Window

The add-on provides an ability to display some information in a pop-up window on a map.

The GeoMap UI component has the openPopup(PopupWindow popupWindow) method that instantly opens the given pop-up window. Class PopupWindow contains two main parameters:

  • point — the geographical point where the pop-up will be opened.

  • content — the HTML content of the pop-up window.

It is also possible to set the additional options for a pop-up window by passing an instance of a PopupWindowOptions class, which contains the following parameters:

  • closeButtonEnabled — whether the close button is enabled in a pop-up window.

  • closeOnClick — whether pop-up should be closed when a user clicks on the map.

  • maxWidth — max width of the pop-up, in pixels (default: 300).

  • minWidth — min width of the pop-up, in pixels (default: 50).

It is possible to attach a pop-up window to a geometry. The pop-up window will be opened when a user clicks on the geometry on a map.

In case of Canvas geometries, you can specify pop-up window in this way:

 CanvasLayer.Point location = canvasLayer.addPoint(address.getLocation());
    PopupWindowOptions popupWindowOptions = new PopupWindowOptions()
                .setCloseOnClick(true)
                .setMaxWidth(400);
    location.setPopupContent(address.getName())
            .setPopupOptions(popupWindowOptions);

In case of VectorLayer, you can specify a popupContentProvider, which is a function that generates content for each geo-object’s pop-up window based on some geo-object parameters.

It can be performed declaratively using the @Install annotation in a screen controller, for example:

 @Install(to = "map.salespersonLayer", subject = "popupContentProvider")
    private String salespersonLayerPopupContentProvider(Salesperson salesperson) {
        return String.format(
                "<b>Name: </b> %s " +
                        "<p>" +
                        "<b>Phone: </b> %s",
                salesperson.getName(),
                salesperson.getPhone());
    }

Appendix A: Maps API

GeoMap UI component

The GeoMap UI component displays a map. The map is built by superposing multiple layers.

GeoMap methods:

  • void addLayer(Layer) — adds a layer to the map.

  • void removeLayer(Layer) — removes a layer from the map.

  • <T extends Layer> T getLayer(String) — returns a layer by its ID. Throws IllegalArgumentException if a layer with the given ID is not present on the map.

  • <T extends Layer> T getLayerOrNull(String layerId) — returns a layer by its ID or null if a layer with the given ID is not present on the map.

  • void setCenter(double, double) — sets the initial geographic center of the map (longitude, latitude).

  • void setZoomLevel(double) — sets map zoom level.

  • void setMaxZoom(int) — sets maximum map zoom level.

  • void setMinZoom(int) — sets minimum map zoom level.

  • GeoMap.Bounds getBounds() — returns the bounds of the map which define the viewport of the map.

  • void setReadOnly(boolean) — enables/disables zooming and dragging the map (changing the viewing area).

  • CanvasLayer getCanvas() — returns the canvas layer of the map.

  • void selectLayer(Layer layer) — sets the selected (active) layer of the map.

  • void selectLayerById(Layer layer) — sets the selected (active) layer of the map by the given id of the layer.

  • Layer getSelectedLayer() — returns the selected layer of the map.

  • addHeatMap(Map<Point, Double>) — adds a heatmap to the map.

  • addHeatMap(Map<Point, Double>, HeatMapOptions) — adds a heatmap to the map with the additional options.

  • void openPopup(PopupWindow) — opens a pop-up info window.

GeoMap events:

  • ClickEvent — event fired after clicking on a map.

  • RightClickEvent — event fired after right click on a map.

  • MoveEndEvent — event fired after changing the map’s viewing area (as a result of zooming/dragging).

  • ZoomEndEvent — event fired after zooming a map.

  • DragEndEvent — event fired after dragging a map.

  • LayerAddedEvent — event fired after adding a layer on a map.

  • LayerRemovedEvent — event fired after removing a layer from a map.

  • SelectedLayerChangedEvent — event fired after changing the map’s selected layer.

Layers

TileLayer methods:

  • void setUrl(String) — sets URL pattern of a tile server.

  • void setAttributionString(String) — sets attribution string.

  • void setOpacity(Double) — sets tiles opacity value in the range between 0.0 (fully transparent) to 1.0 (fully opaque).

WMSTileLayer methods:

  • void setUrl(String) — sets URL of a WMS service.

  • void setOpacity(Double) — sets tiles opacity value in the range between 0.0 (fully transparent) to 1.0 (fully opaque).

  • void setCrs(CRS) — sets CRS to be used in the WMS.

  • void setLayers(String) — sets WMS service layers to display on a map (as a comma-separated list).

  • void setStyles(String) — sets comma-separated list of WMS styles.

  • void setFormat(String) — sets WMS image format.

  • void setTransparent(boolean) — sets whether the layer is to be transparent.

  • void setVersion(String) — sets WMS service version.

VectorLayer methods:

  • void setStyleProvider(Function<? super T, GeometryStyle>) — sets a function that determines geometry style for a given geo-object. In CUBA 7.0+ screens you can perform this declaratively using the @Install annotation in the screen controller.

  • setPopupContentProvider(Function<? super T, String>) — sets a function that determines content for bound pop-ups which will be opened by clicking on geo-objects on a map. In CUBA 7 screens you can perform this declaratively using the @Install annotation in the screen controller, for example:

    @Install(to = "map.territoryLayer", subject = "popupContentProvider")
    private String territoryLayerPopupContentProvider(Territory territory) {
    return territory.getName();
    }
  • void setPopupWindowOptions(PopupWindowOptions) — sets the explicit style parameters for geo-object’s bound pop-ups.

  • void setSelectedGeoObject(T) — sets the selected geo-object of the layer.

VectorLayer events:

  • GeoObjectSelectedEvent — event fired when selected geo-object has changed.

CanvasLayer methods:

  • CanvasLayer.Point addPoint(org.locationtech.jts.geom.Point) — adds a point to the canvas.

  • CanvasLayer.Polyline addPolyline(org.locationtech.jts.geom.LineString) — adds a polyline to the canvas.

  • CanvasLayer.Polygon addPolygon(org.locationtech.jts.geom.Polygon) — adds a polyline to the canvas.

  • void removePoint(CanvasLayer.Point) — removes a point from the canvas.

  • void removePolyline(CanvasLayer.Polyline) — removes a polyline from the canvas.

  • void removePolygon(CanvasLayer.Polygon) — removes a polygon from the canvas.

  • void clear() — removes all geometries from the canvas.

  • void drawPoint(Consumer<CanvasLayer.Point>) — activates the point drawing mode on the map. After the point is drawn, the given consumer action is applied to it.

  • void drawPolyline(Consumer<CanvasLayer.Polyline>) — activates the polyline drawing mode on the map. After the polyline is drawn, the given consumer action is applied to it.

  • void drawPolygon(Consumer<CanvasLayer.Polygon>) — activates the polygon drawing mode on the map. After the polygon is drawn, the given consumer action is applied to it.

addPoint method returns an instance of CanvasLayer.Point which controls the added point on the canvas.

CanvasLayer.Point methods:

  • org.locationtech.jts.geom.Geometry getGeometry() — returns the geometry value.

  • setEditable(boolean) — sets whether the geometry is to be modifiable.

  • setStyle(PointStyle) — applies a style to the point.

  • setPopupContent(String) — adds a pop-up window to be opened as user clicks on the point.

  • setPopupOptions(PopupWindowOptions) — specifies options for a pop-up window added by previous method.

CanvasLayer.Point events:

  • ClickEvent — event fired after clicking on the point.

  • RightClickEvent — event fired after right click on the point.

  • ModifiedEvent — event fired after modifying the point (as a result of drag and drop via UI).

addPolyline method returns an instance of CanvasLayer.Polyline which controls the added polyline on the canvas.

CanvasLayer.Polyline methods:

  • org.locationtech.jts.geom.Geometry getGeometry() — returns the geometry value.

  • setEditable(boolean) — sets whether the geometry is to be modifiable.

  • setStyle(PolylineStyle) — applies a style to the polyline.

  • setPopupContent(String) — adds a pop-up window to be opened as user clicks on the polyline.

  • setPopupOptions(PopupWindowOptions) — specifies options for a pop-up window added by previous method.

CanvasLayer.Polyline events:

  • ClickEvent — event fired after clicking on the polyline.

  • RightClickEvent — event fired after right click on the polyline.

  • ModifiedEvent — event fired after modifying the polyline via UI.

addPolygon method returns an instance of CanvasLayer.Polygon which controls the added polygon on the canvas.

CanvasLayer.Polygon methods:

  • org.locationtech.jts.geom.Geometry getGeometry() — returns the geometry value.

  • setEditable(boolean) — sets whether the geometry is to be modifiable.

  • setStyle(PolygonStyle) — applies a style to the polygon.

  • setPopupContent(String) — adds a pop-up window to be opened as user clicks on the polygon.

  • setPopupOptions(PopupWindowOptions) — specifies options for a pop-up window added by previous method.

CanvasLayer.Polygon events:

  • ClickEvent — event fired after clicking on the polygon.

  • RightClickEvent — event fired after right click on the polygon.

  • ModifiedEvent — event fired after modifying the polygon via UI.

You can subscribe to events fired by a particular canvas geometry or you can subscribe to events fired by all points, polylines or polygons using the CanvasLayer interface.

Appendix B: Glossary

Web Map Service

Web Map Service (WMS) is an OGC standard for serving up map images over HTTP. Map images are usually generated by a map server using data from GIS database. This format is similar to map tiles, but more general and not so well optimized for using in web applications.

WMS supports a number of different request types, but the main operations are:

  • GetCapabilities — operation that returns an XML document describing the service (supported parameters, image formats, available layers, etc.).

  • GetMap — operation that returns a map image for a specified area and content. The add-on uses this operation to obtain images from WMS.

It’s important not to confuse the concept of the add-on’s layer with the layer in WMS. WMS provides a set of layers defined in the GetCapabilities XML document. The WMS Layer of the add-on displays the resulting images provided by WMS. These images are being built using one or more layers in WMS.

The add-on does not work with GetCapabilities operation, so you can find out the information about the available layers in WMS in one of the following ways:

  • Find it in GetCapabilities XML document. You can obtain it by sending a URL request to the server and get the response as an XML document. The URL request looks like this: BASE_WMS_URL?request=GetCapabilities.

  • Use a GIS software (such as QGIS). Here is a tutorial on how to work with WMS in QGIS.

Useful links:

  • OSM WMS Servers.

XYZ tiles

XYZ is a de facto OpenStreetMap standard, also known as Slippy Map Tilenames, defining scheme for tiles that are served through a web server.

These tiles can be accessed via URL following certain pattern: http://…​/{z}/{x}/{y}.png, where z is the zoom level, and x,y identify the tile.

Useful links:

  • Tile servers based on OpenStreetMap data.

  • Tile providers preview — here you can find and preview various XYZ tile services. Some of them are free, while others require registration and may have free tile requests limit. Be sure to check the providers usage policies before using them.

  • Mapbox tile API.

  • HERE tile API.