Area

The Area field displays a geographical area as an interactive map on the Show view and provides a text input for editing its coordinates on forms.

# app/avo/resources/city.rb
field :city_center_area, as: :area

By default, the field treats the coordinates as a polygon, adds no labels or custom colors, and is hidden on the Index view. Maps follow Avo's light and dark color schemes using the configured map styles, or OpenFreeMap when no provider is configured and no Mapbox token is set.

Enable maps

Add the mapkick-rb gem (not mapkick) to your Gemfile:

# Gemfile
gem "mapkick-rb"

Avo renders maps with OpenFreeMap by default: no registration, no API key, no request limit, and attribution is handled for you.

If you'd rather use Mapbox, set the MAPBOX_ACCESS_TOKEN environment variable to a valid Mapbox key and Avo will default to Mapbox styles instead. Pin either provider, or your own light/dark pair, with config.map_view. To override a single map, see Customize the map.

Store and edit coordinates

Store a GeoJSON coordinates array in one database column, such as a json column. Store just the coordinates, not a complete GeoJSON geometry or Feature object. Coordinates use longitude, latitude order.

For example, this polygon outlines an area in central Paris:

[[[2.3342, 48.8674], [2.3396, 48.8600], [2.3253, 48.8567], [2.3245, 48.8639], [2.3342, 48.8674]]]

On the Edit view, edit the coordinates as JSON in the text input. A blank value renders a dash instead of a map on the Show view.

Configure the area

Display multiple polygons

If your column holds several polygons, set geometry to :multi_polygon and store an array of polygon coordinate arrays. For a single polygon, store its exterior ring followed by any holes. See the GeoJSON geometry specification for the coordinate structure.

# app/avo/resources/city.rb
field :city_center_area, as: :area, geometry: :multi_polygon

WARNING

Avo does not validate the geometry type or coordinates. The coordinates must match the selected geometry, and each linear ring must be closed by repeating its first position at the end.

Customize the map

Use mapkick_options to change the map's appearance or enable controls. For example, choose a different style for this field and add navigation controls:

# app/avo/resources/city.rb
field :city_center_area,
  as: :area,
  mapkick_options: {
    style: "https://tiles.openfreemap.org/styles/liberty",
    controls: true
  }

INFO

Avo follows the color scheme and swaps the map between its light and dark styles automatically. Pass your own style and Avo leaves the map exactly as you set it, dark mode included.

Label and color the area

Use datapoint_options to attach a label, tooltip, or color to the area:

# app/avo/resources/city.rb
field :city_center_area,
  as: :area,
  datapoint_options: {
    label: "Paris City Center",
    tooltip: "Bonjour mes amis!",
    color: "#009099"
  }

Full example

# app/avo/resources/city.rb
field :city_center_area,
  as: :area,
  geometry: :polygon,
  mapkick_options: {
    style: "https://tiles.openfreemap.org/styles/liberty",
    controls: true
  },
  datapoint_options: {
    label: "Paris City Center",
    tooltip: "Bonjour mes amis!",
    color: "#009099"
  }

For labels, visibility, placeholders, and other shared field settings, see Common field options.