OpenLayers Map is a free, open-source map component for OutSystems 11 Reactive Web and Mobile apps. It is based on OpenLayers 10.6.0 and needs no API key and no paid map service.
The component is a Library module (OpenLayersMap) with one block, Map, and a set of public client actions. Every action takes the MapId you gave the block, so several maps can live on the same screen.
GETTING STARTED
1. Add a dependency on OpenLayersMap and select the Map block, the MapMarker structure and the Map_* actions you need.
2. Drag the Map block onto a screen and set a unique MapId (e.g. "MainMap").
3. Optionally bind a MapMarker list to Markers and handle the events you need.
4. Call the Map_* actions from your screen actions, using the same MapId.
The OpenLayers Map Demo app shows every feature.
MAP BLOCK - INPUTS
- MapId (mandatory): unique identifier of the map on the screen.
- CenterLatitude, CenterLongitude, Zoom: initial view. Changing them recentres or zooms the map.
- Height: CSS height of the map (e.g. 400px, 60vh).
- BaseLayer: OSM (default), XYZ or WMS.
- BaseLayerUrl: XYZ tile URL template ({x}/{y}/{z}) or WMS service URL.
- WMSLayers: comma-separated WMS layer names.
- Attributions: attribution text for XYZ/WMS layers.
- Authorization: optional Authorization header value sent with every tile request (the tile service must allow CORS). Get it from a server action; never hard-code credentials.
- Markers: list of MapMarker. Changing the list refreshes the markers.
- ClusterMarkers: groups nearby markers into clusters.
- FitToMarkers: zooms to show all markers whenever they change.
MAP BLOCK - EVENTS
- OnReady(MapId): the map is created and the actions can be used.
- OnMapClick(Latitude, Longitude): click outside markers and features (not while drawing).
- OnMarkerClick(MarkerId).
- OnFeatureClick(LayerId, FeatureId): click on a feature of a GeoJSON layer.
- OnDrawEnd(GeoJSON, AreaHa, IsValid): a shape was finished or edited. GeoJSON holds all drawn shapes (WGS84), AreaHa their total area in hectares, IsValid is False for self-intersecting polygons.
- OnDrawOutOfBounds(Message): the user tried to draw or move a vertex outside the allowed area.
MAPMARKER STRUCTURE
Id, Latitude, Longitude, Title (plain-text popup), IconUrl (optional image anchored at the bottom centre), Color (CSS colour of the default circle marker).
CLIENT ACTIONS
View:
- Map_SetCenter(Latitude, Longitude, Zoom): animated move. Zoom 0 keeps the current zoom.
- Map_SetZoom(Zoom), Map_GetView() returning Latitude, Longitude and Zoom.
- Map_UpdateSize(): call it when the map becomes visible inside tabs, popups or collapsible areas.
- Map_FitToAll(): zooms to all markers, layers and drawn shapes.
Markers:
- Map_SetMarkers(Markers), Map_ClearMarkers(), Map_FitToMarkers().
GeoJSON layers:
- Map_AddGeoJSONLayer(LayerId, GeoJSON, StrokeColor, FillColor, StrokeWidth, FitToLayer, LabelProperty, TooltipProperty): adds or replaces a layer. LabelProperty and TooltipProperty name the feature properties shown as labels and hover tooltips.
- Map_RemoveLayer(LayerId), Map_SetLayerVisible(LayerId, IsVisible), Map_FitToLayer(LayerId).
Drawing and editing:
- Map_StartDrawing(GeometryType, SingleShape, ShowLiveArea): Polygon, LineString, Point or Circle. Shows the area or length live while drawing.
- Map_StopDrawing(), Map_UndoLastPoint(), Map_ClearDrawing().
- Map_LoadDrawing(GeoJSON, IsEditable, FitToDrawing): loads existing shapes, e.g. to edit a saved polygon.
- Map_GetDrawing() returning GeoJSON, AreaHa and IsValid.
- Map_SetDrawBoundary(GeoJSON, OutOfBoundsMessage, FitToBoundary) and Map_ClearDrawBoundary(): restrict drawing and editing to a polygon, shown as a dashed red outline.
While editing: drag a vertex to move it, drag the middle of an edge to add a vertex, click a vertex to remove it. This works with mouse and touch.
NOTES
- All coordinates and GeoJSON going in and out are WGS84 (EPSG:4326). The map is displayed in Web Mercator.
- Areas are geodesic, calculated on the sphere, in hectares.
- Circles are converted to 64-point polygons, because GeoJSON has no circle type.
- Styling is set per layer, not per feature.
- For advanced cases, the OpenLayers map object is available in JavaScript through OLMap.getMap(MapId).
- If your environment uses a Content Security Policy, allow the tile servers you use (e.g. tile.openstreetmap.org).
- When using OpenStreetMap tiles, follow the OSM tile usage policy. Use your own or a commercial tile service for heavy traffic.
- OpenLayers: BSD 2-Clause.
- JSTS: Eclipse Distribution License 1.0.
- Map data: © OpenStreetMap contributors (ODbL), shown automatically on the map.