developer guide
Map View: A 3D Map Beside Your Data Grid
The rows a grid already holds, drawn on a 3D map that filters, searches and selects alongside it. Points, extruded columns, polygons and routes, with OpenStreetMap buildings when you want them.
One call, a live map
Import the map view module and hand createMapView a grid and where each row's place
comes from: a latitude and longitude pair, a geometry column, or a path of coordinates. The map
fills a container of your own, or sits beside the grid, in a tab, or in a pop-out window. Rows draw
as markers or extruded columns, polygons as extruded areas, and routes as lines, coloured by a
category or a numeric ramp.
import { createMapView } from '@toclocoinc/lattice-grid/modules/mapview';
const map = createMapView(grid, {
container: '#map',
geometry: { lat: 'lat', lng: 'lng' }, // or { geojson: 'shape' }, or { path: 'route' }
layer: 'column', // markers, extruded columns, polygons or routes
elevation: 'premisesPassed', // a numeric column sets each column's height
color: { field: 'status', map: { live: '#1b7f3b', planned: '#a96a0b' } },
buildings: true, // OpenStreetMap 3D buildings in the basemap
});
map.on('feature:click', ({ row }) => console.log(row)); // a click also selects and scrolls the grid to the row
The grid's own filter, search and selection
Filtering, searching or grouping the grid redraws the map on the next frame, so a build schedule narrowed to one region shows only that region on the map. Selecting rows in the grid flies the map to them and highlights them; clicking a feature on the map selects its row and scrolls the grid to it. A hover tooltip shows the grid's own formatted cell text, not a second copy of the data.
Routes with an animated flow
A path geometry draws as a route, and an optional animated flow travels along it, useful for traffic, circuits or a delivery network in motion. The flow pauses while the tab is hidden and stays still for a reader who prefers reduced motion.
createMapView(grid, {
geometry: { path: 'route' },
layer: 'path',
flow: { speed: 0.4, trail: 0.25 }, // an animated trail travels each route
width: 'volume', // a numeric column widens busier routes
});
Drawing and editing
The map can take shapes of its own as well as show your rows. map.draw.setMode turns a click
or a drag into a point, a line, a polygon, a circle (dragged from its centre) or a rectangle (dragged
corner to corner), and Escape cancels the shape in progress. In 'edit' mode a click selects a
shape, Shift-click adds another, a drag on a corner reshapes it, a drag on a midpoint adds a corner, a drag
on the shape moves it, Delete removes it, and undo() and redo() step through every
change. A readout beside the cursor gives a line's length or an area's size, snapping and drawing rules keep
a shape exact, and all of it works by touch. Drawn shapes are separate from the grid's rows: you read them
back as GeoJSON with getFeatures().
map.draw.setMode('polygon'); // 'point' | 'line' | 'polygon' | 'circle' | 'rectangle' | null
map.on('draw:finish', ({ feature }) => console.log(feature)); // a GeoJSON Feature
map.draw.setMode('edit'); // click to select, drag a corner to reshape, drag a shape to move it
map.draw.undo(); // Ctrl/Cmd-Z does the same; redo() steps forward
map.draw.getFeatures(); // every drawn shape as a GeoJSON FeatureCollection
// Snap to a layer of your own, and refuse what breaks a rule:
map.draw.setMode('line', {
snap: { layers: ['chambers'], tolerance: 10 },
constraints: { maxVertices: 20, minSegmentLength: 5 },
});
Loading the map…
Pick a shape, draw it on the map, then press Edit and click it to select. Drag it to move it, or drag a corner to reshape. Maps and tiles load on demand.
Move a grid row by dragging its point
Set moveRows: true (it is off by default) and, in edit mode, a row placed by
geometry: { lat, lng } can be dragged. On release the new latitude and longitude are
written through the grid's own editing, exactly as if you had typed them into the two cells, so
validation, beforeEdit, undo and change events all apply, and the two cells are one edit. A
refused edit puts the point back. With the option off, a drag on a row pans the map as before. Rows
are sized in pixels here with radiusUnits: 'pixels'; points also stop growing at
radiusMaxPixels (24 by default) when you zoom in.
const map = createMapView(grid, {
container: '#map',
geometry: { lat: 'lat', lng: 'lng' },
moveRows: true, // off by default
radius: 9,
radiusUnits: 'pixels', // a size on screen, the same at every zoom
});
map.draw.setMode('edit'); // drag a row's point; on release the grid's own editing
// writes the new lat and lng as one edit and one undo step
Loading the map…
For a telecoms team, the build schedule, premises list or fault log already open in a grid becomes a 3D map of the network with no extra integration. The geospatial guide covers the geometry column type and the built-in maps this module sits beside.