Rover.Marker (Rover v0.1.0)

Copy Markdown View Source

A point on the map.

You rarely build one by hand. Rover.Components.map/1 runs every entry of its markers list through new!/1, so plain maps and your own Ecto schemas work as-is provided they carry an id and a coordinate:

%{id: 1, lat: 45.75, lon: 4.85, label: "Lyon"}
%Client{id: 1, latitude: 45.75, longitude: 4.85, name: "Lyon"}

For the second form, tell Rover which fields to read:

Rover.Marker.new!(client, lat: :latitude, lon: :longitude, label: :name)

Fields

FieldTypeMeaning
:idtermRequired. Stable identity used to diff the map.
:lat / :lonfloatRequired. See Rover.Geo.
:labelstringText drawn next to the marker.
:colorstringCSS colour of the default pin, e.g. "#e11d48".
:iconstringURL of an image to use instead of the default pin.
:scalefloatSize multiplier applied to the pin or icon.
:tooltipstringShown on hover. Defaults to :label.
:draggablebooleanLets the user move the marker (see on_marker_drag_end).
:datamapEchoed back verbatim in marker events.

The identity is :id. Changing anything else updates that marker in place; changing the id removes one marker and adds another.

Ids travel through JSON

Integers and strings round-trip unchanged, so an event handler matching on %{"id" => 1} works. Atoms do not: :depot is delivered back as "depot", and a handler matching id == :depot will never fire. Use integers or strings for ids you intend to match on.

Summary

Types

id()
t()

Functions

dump(marker)

Renders a marker as the compact map handed to the JavaScript runtime.

new!(source, opts \\ [])

Normalises source into a Rover.Marker.

new_all!(markers, opts \\ [])

Normalises a list of markers. Nil entries are dropped.

Types

id()

@type id() :: String.t() | integer() | atom()

t()

@type t() :: %Rover.Marker{
  color: String.t() | nil,
  data: map() | nil,
  draggable: boolean(),
  icon: String.t() | nil,
  id: id(),
  label: String.t() | nil,
  lat: float(),
  lon: float(),
  scale: float() | nil,
  tooltip: String.t() | nil
}

Functions

dump(marker)

@spec dump(t()) :: map()

Renders a marker as the compact map handed to the JavaScript runtime.

nil fields are dropped so that the payload sent over the wire stays small.

Examples

iex> Rover.Marker.new!(%{id: 1, lat: 45.75, lon: 4.85}) |> Rover.Marker.dump()
%{id: 1, lat: 45.75, lon: 4.85}

new!(source, opts \\ [])

@spec new!(
  t() | map(),
  keyword()
) :: t()

Normalises source into a Rover.Marker.

opts maps Rover fields onto keys of source, for schemas that name things differently. Every option takes a key (atom or string) or a 1-arity function.

Examples

iex> Rover.Marker.new!(%{id: 1, lat: 45.75, lon: 4.85, name: "Lyon"}) |> Rover.Marker.dump()
%{id: 1, lat: 45.75, lon: 4.85, label: "Lyon"}

iex> Rover.Marker.new!(%{ref: "a", lat: 45.75, lng: 4.85}, id: :ref).id
"a"

iex> Rover.Marker.new!(%{id: 1, lat: 45.75, lon: 4.85}, label: fn m -> "client " <> to_string(m.id) end).label
"client 1"

new_all!(markers, opts \\ [])

@spec new_all!(
  Enumerable.t(),
  keyword()
) :: [t()]

Normalises a list of markers. Nil entries are dropped.