Location

The Location field displays a point on a map and lets users edit its latitude and longitude.

# app/avo/resources/city.rb
field :coordinates, as: :location, stored_as: [:latitude, :longitude]

By default, the field is hidden on the index view and displays an interactive map on the show view. Without stored_as, it uses the field's own attribute and renders one text input for editing coordinates.

Display an interactive map

Add mapkick-rb (not mapkick) to your application:

# 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. Avo then defaults to Mapbox styles. Pin either provider, or your own light/dark pair, with config.map_view.

Edit coordinates in separate columns

If your model stores coordinates in two columns, use stored_as as in the opening example. List latitude first and longitude second; the column names can be different from latitude and longitude.

This displays two separate text inputs on the edit form and uses those attributes to position the map.

Use a single coordinate attribute

Omit stored_as if your model already exposes a coordinate pair through one attribute:

# app/avo/resources/city.rb
field :coordinates, as: :location

The edit input accepts comma-separated coordinates such as 44.427946,26.102451, in latitude/longitude order. On submission, Avo splits that text into an array before assigning it to the model. The attribute must return an indexable coordinate pair for map rendering, such as [44.427946, 26.102451].

Coordinate storage

A plain text column containing "44.427946,26.102451" is not split when the map is displayed. Use an array-compatible attribute, a model getter/setter that converts the stored value, or two columns with stored_as.

Customize the map's appearance

Set zoom to change the initial zoom level of the interactive map:

# app/avo/resources/city.rb
field :coordinates, as: :location, stored_as: [:latitude, :longitude], zoom: 12

For other map settings, pass mapkick_options. For example, choose a style for this field:

# app/avo/resources/city.rb
field :coordinates,
  as: :location,
  stored_as: [:latitude, :longitude],
  mapkick_options: {
    style: "https://tiles.openfreemap.org/styles/liberty",
    controls: true
  }

See the Mapkick options for other settings.

Dark mode

Avo follows the color scheme and swaps between the configured light and dark styles automatically. An explicit mapkick_options[:style] disables that automatic switching for this map.

Display a static map

If you want an image instead of an interactive map, enable static:

# app/avo/resources/city.rb
field :coordinates,
  as: :location,
  stored_as: [:latitude, :longitude],
  static: true,
  mapkick_options: {
    style: "mapbox://styles/mapbox/satellite-v9"
  }

Mapbox required

Static maps use Mapbox's Static Images API, which OpenFreeMap has no equivalent for. Add the mapkick-static gem to your Gemfile and set MAPBOX_ACCESS_TOKEN to a valid Mapbox key.

The Preview view always renders a static map, even when static is not enabled.

Options reference

See the Location API for field-specific options and the common field options for shared settings.