# Rover
**Maps for Phoenix LiveView, powered by [OpenLayers](https://openlayers.org/).**
[](https://hex.pm/packages/rover)
[](https://hexdocs.pm/rover)
OpenLayers is a serious mapping engine. It is also ten concepts deep before you
can put three pins on a map: `Map`, `View`, `Layer`, `Source`, `Feature`,
`Geometry`, `Style`, `Overlay`, `Interaction`, `Control`.
Rover keeps the engine and removes the ceremony.
```heex
<.map id="clients" center={{45.75, 4.85}} zoom={12} markers={@clients} />
```
```elixir
assign(socket,
clients: [
%{id: 1, lat: 45.76, lon: 4.83, label: "Atelier"},
%{id: 2, lat: 45.74, lon: 4.86, label: "Dépôt"}
]
)
```
That is the whole thing. Assign a list of maps, get a map. Assign a different
list, and Rover updates only the markers that actually changed.
## Why not just write a hook?
Because you already can, and the first version is genuinely short. Three pins on
a tile layer is a dozen lines of JavaScript and an afternoon.
The afternoon after that is the one to think about. A `phx-hook` has no opinion
about what happens when the list changes, so you write the reconciliation — and
if you write the obvious version, clearing the layer and redrawing it, you also
get the flicker, the interrupted pan and the popup that closes itself. Then the
framing, because someone will open a map with one marker and another with two
hundred. Then `updated()`, or you discover that changing the element's `id` is
the only way to get new data in. Then the coordinate order, once, in the wrong
direction. Then the attribution, which is a licence condition rather than a
detail.
None of that is hard. All of it is work you have done before, and Rover has done
it here, with tests that assert the reconciliation by object identity so it stays
done.
The other half of the bet is the engine underneath. OpenLayers carries
projections, huge vector layers, WMS/WMTS and the rest of the serious GIS
surface — so the day your three pins turn into a cadastral overlay, the ceiling
is somewhere else entirely.
## Installation
```elixir
def deps do
[{:rover, "~> 0.5"}]
end
```
Rover ships a prebuilt JavaScript bundle with OpenLayers already inside it, so a
stock `mix phx.new` application — no `npm`, no `node_modules`, no
`package.json` — works as-is.
In `assets/js/app.js`:
```js
import { RoverHooks } from "../../deps/rover/priv/static/rover.js"
const liveSocket = new LiveSocket("/live", Socket, {
params: { _csrf_token: csrfToken },
hooks: { ...RoverHooks }
})
```
In `assets/css/app.css`:
```css
@import "../../deps/rover/priv/static/rover.css";
```
And in the `html_helpers` block of your `lib/my_app_web.ex`:
```elixir
import Rover.Components
```
## Markers
A marker is anything with an id and a coordinate. Plain maps, structs, Ecto
schemas:
```elixir
%{id: 1, lat: 45.75, lon: 4.85, label: "Atelier"}
```
| Field | Meaning |
|---|---|
| `:id` | **Required.** Stable identity used to diff the map. |
| `:lat` / `:lon` | **Required.** Also accepted: `:latitude`/`:longitude`, `:lng`. |
| `:label` | Text drawn next to the marker. Falls back to `:name` or `:title`. |
| `:color` | Colour of the default pin, e.g. `"#e11d48"`. |
| `:emoji` | An emoji drawn in place of the pin, e.g. `"🏠"`. |
| `:icon` | URL of an image to use instead of the pin. |
| `:scale` | Size multiplier. |
| `:tooltip` | Shown on hover. Defaults to the label. |
| `:draggable` | Lets the user move it — see `on_marker_drag_end`. |
| `:data` | Any map; echoed back verbatim in events. |
If your schema names things differently, say so once:
```heex
<.map
id="stores"
markers={@stores}
marker_fields={[lat: :latitude, lon: :longitude, label: :trade_name]}
/>
```
## Events
```heex
<.map id="clients" markers={@clients} on_marker_click="select_client" />
```
```elixir
def handle_event("select_client", %{"id" => id}, socket) do
{:noreply, assign(socket, selected: id)}
end
```
| Attribute | Payload |
|---|---|
| `on_marker_click` | `%{"id" =>, "lat" =>, "lon" =>, "data" =>}` |
| `on_cluster_click` | `%{"count" =>, "ids" => [id, …], "lat" =>, "lon" =>}` |
| `on_shape_click` | `%{"id" =>, "lat" =>, "lon" =>, "data" =>}` |
| `on_map_click` | `%{"lat" =>, "lon" =>}` |
| `on_move_end` | `%{"center" => [lat, lon], "zoom" =>, "bbox" => %{"south" =>, "west" =>, "north" =>, "east" =>}}` |
| `on_marker_drag_end` | `%{"id" =>, "lat" =>, "lon" =>}` |
| `on_shape_edit_end` | `%{"id" =>, "geometry" =>, "properties" =>, "data" =>}` |
Inside a `Phoenix.LiveComponent`, add `target={@myself}`.
## Shapes
Outlines, routes and zones come in as **GeoJSON**:
```heex
<.map id="parcel" shapes={@parcels} tiles={:ign_ortho} />
```
```elixir
assign(socket,
parcels: [
%{id: p.id, geometry: p.cadastral_outline, color: "#16a34a", fill_opacity: 0.2}
]
)
```
A bare geometry, a `Feature` or a `FeatureCollection`; atom or string keys; or an
undecoded JSON string, so `ST_AsGeoJSON` output goes straight in. Fields:
`:color`, `:width`, `:fill_color`, `:fill_opacity`, `:label`, `:tooltip`, `:rev`,
`:data`, `:editable`.
Shapes are **the one place Rover is not latitude-first** — GeoJSON is defined as
`[longitude, latitude]` and the standard wins, because geometry is never typed by
hand. See `Rover.Shape` for why.
A map with shapes and no markers frames the geometry, so a parcel page needs no
`center`.
### Letting the user edit a shape's vertices
`editable: true` lets the user drag a shape's vertices directly on the map, the
geometry equivalent of `:draggable` on a marker:
```elixir
%{id: p.id, geometry: p.cadastral_outline, editable: true}
```
```elixir
def handle_event("on_shape_edit_end", %{"id" => id, "geometry" => geometry}, socket) do
# Persist or reject. Either way, see the :rev note below.
{:noreply, socket}
end
```
Only a shape backed by a single feature can be edited — a `FeatureCollection` of
several has no one geometry a drag could write back to a single `:geometry`
field, and stays read-only regardless of `:editable`.
`on_shape_edit_end`'s `"geometry"` is always a **bare** geometry — if the
shape's own `:geometry` was a `Feature`, its `"properties"` travel in their own
key instead, `nil` for a shape that was already bare. Wrap them back up
yourself if you merge the result straight into `:geometry`:
```elixir
def handle_event("on_shape_edit_end", %{"id" => id, "geometry" => geometry, "properties" => properties}, socket) do
geometry = if properties, do: %{"type" => "Feature", "properties" => properties, "geometry" => geometry}, else: geometry
# ...
end
```
**Rejecting an edit needs an observable `:rev`.** The client already moved the
vertex by the time `on_shape_edit_end` fires; reassigning `:shapes` with the
exact same geometry produces byte-identical JSON, which never reaches the
browser at all — nothing in the rendered output changed, so nothing is sent.
What snaps the shape back to the server's truth is bumping `:rev` (the default
`:erlang.phash2(geometry)` already does this whenever the geometry itself
changes; rejecting an edit means the geometry does *not* change, so `:rev` has
to be bumped some other way, deliberately).
### Letting the user draw a new one
`:editable` reshapes a geometry that already exists. Drawing is the other half,
and it is a **mode** rather than an attribute — there is no shape yet to hang a
flag on, so the server arms the map for a gesture the way `fly_to` moves it:
```elixir
def handle_event("draw_parcel", _params, socket) do
{:noreply, Rover.start_drawing(socket, "parcels", type: :polygon)}
end
```
```heex
<.map id="parcels" shapes={@parcels} on_draw_end="drew" />
```
```elixir
def handle_event("drew", %{"type" => _type, "geometry" => geometry}, socket) do
parcel = %{id: System.unique_integer([:positive]), geometry: geometry, editable: true}
{:noreply,
socket
|> assign(parcels: socket.assigns.parcels ++ [parcel])
|> Rover.stop_drawing("parcels")}
end
```
`on_draw_end` is the one event with no `"id"`: the shape does not exist until
you make one, so naming it is yours to do — the same way it would be for a row
you are about to insert.
Four things worth knowing:
* **The mode stays armed** until `Rover.stop_drawing/2`. A user asked to trace
four parcels traces four without going back to the toolbar. Drop the
`stop_drawing` above if that is what you want.
* **Escape abandons the sketch in progress** and leaves the mode armed, the way
it does in every drawing tool. The server is not told: it armed a mode, and
the mode is still armed.
* **`:type` is `:polygon`, `:line` or `:point`.** There is no `:circle` —
OpenLayers can draw one, GeoJSON has no way to represent one, and a shape that
cannot round-trip through `Rover.Shape` is one the server could never store or
send back.
* **New points snap to the shapes already on the map**, so a parcel traced
against its neighbour shares that border instead of leaving a sliver.
* **While the mode is armed the map claims every click.** Not just
`on_map_click`: markers, shapes and clusters stop answering too, popups
included, because a click that places a vertex is not a click on the thing
underneath it. Since the mode persists until you stop it, leaving it armed
leaves the map's other click behaviour off with it.
A map rendered with `interactive={false}` refuses to arm, and locking one that
is already drawing cancels the mode outright rather than remembering it.
### Geometry is diffed by revision, not by hashing
Markers hash their coordinate — two numbers. A route is thousands of points, so
shapes carry a `:rev` computed once per render on the server
(`:erlang.phash2(geometry)` by default). Pass your own if you have something
better:
```elixir
%{id: p.id, geometry: p.geom, rev: p.updated_at}
```
Same id and same `:rev` means the client leaves that feature alone.
## Clustering
Hundreds of markers are a wall of overlapping icons. Grouping them is one attribute:
```heex
<.map id="clients" markers={@clients} cluster={true} />
<.map id="clients" markers={@clients} cluster={[distance: 60, zoom_on_click: false]} />
```
A group of one is drawn as its own marker, so nothing looks clustered until it
actually is. Clicking a group zooms into it — without that a cluster is a dead end,
showing you that twelve things are there with no way to reach them — and sends
`on_cluster_click` with the member ids.
Reconciliation is untouched by any of this. `ol/source/Cluster` *wraps* the marker
source rather than replacing it, so the markers are still diffed by id exactly as
before; only what is drawn changes.
Two consequences worth knowing:
* **A grouped marker has no popup.** Its pin is drawn at the group's centre, so a
popup would point at empty space. An open popup closes when its marker joins a
group; it does not reopen by itself when you zoom back in.
* **`:draggable` markers cannot be dragged at all while `cluster` is set**, even
standing alone — every marker is wrapped by a cluster feature once clustering is
on, and dragging that would move the wrapper rather than the marker.
## Heatmaps
Five hundred markers are a wall of overlapping icons. A heat field answers a
different question — *where is there a lot of this?*
```heex
<.map id="deliveries" heatmap={@rows} heatmap_style={[radius: 12, blur: 20]} />
```
A point needs only a coordinate; `:weight` is relative, 0 to 1, and defaults to 1:
```elixir
%{lat: 45.75, lon: 4.85}
%{lat: 45.75, lon: 4.85, weight: 0.4}
```
No `:id` here, unlike markers and shapes. A heatmap is an aggregate — no individual
point is visible in the result — so per-point identity would be ceremony that buys
nothing. It is diffed by revision instead, like shapes, which also means a
style-only change restyles the layer without rebuilding the field.
## Popups
A slot, rendered once per marker and shown on click with no server round-trip:
```heex
<.map id="clients" markers={@clients}>
<:popup :let={marker}>
{marker.label}
{marker.data && marker.data.address}
```
Shapes get their own slot, and open where the geometry was clicked rather than at
its centroid — pointing at the middle of a long route would point at nothing the
user did:
```heex
<:shape_popup :let={shape}>