AugustMiller / kirby-map-field

🗺 An easy way to use maps and location data in Kirby.
MIT License
41 stars 4 forks source link
kirby kirby-plugin mapping

Map Field

I've found that adding location data to Kirby CMS forms to be super useful.

Unfortunately, this isn't one of the many fields available to us, out of the box.

Features

Kirby Map Field Screenshot

Getting Started

If you like the command line, adding this to your project is super easy.

Be sure you have a plugins folder in your site folder, then:

cd /path/to/your/project
git submodule add https://github.com/AugustMiller/kirby-map-field.git site/plugins/map

It's important that the folder be named map, because kirby looks for the plugin class's definition in a PHP file with the same name as the folder.

You can also directly download an archive of the current project state, rename the folder to map, and add it to the site/plugins folder of your project.

Once you've added the plugin, you can add a map field to your blueprints, like this:

fields:
  location:
    label: Location
    type: map
    center:
      lat: 45.5230622
      lng: -122.6764816
      zoom: 9
    help: >
      Move the pin wherever you'd like, or search for a location!

The center key allows you to customize the initial position and zoom level of the map interface.

You can also set global defaults, in your config.php:

c::set('map.defaults.lat', 45.5230622);
c::set('map.defaults.lng', -122.6764816);
c::set('map.defaults.zoom', 9);

These options will be overridden by any set on individual fields. Without either configured, it will default to hard-coded values.

Keys

Google recently announced that all usage must be accompanied by a valid browser key. This means that in order to use the Maps and Geocoding APIs, you must apply for a key in Google's Developer Console/API Manager, and add it to your installation's configuration file:

c::set('map.key', 'your-browser-key');

Access to the Maps API is free up to 25,000 loads per day. Be aware that you will need to manually enable both the JS Maps API and the Geocoding API individually.

Usage

The Map Field stores data in YAML.

You must manually transform the field to an associative array by calling the yaml field method.

The resulting array can be used just like any other:

$page->location()->yaml()['lat'];
// Or!
$location = $page->location()->yaml();
echo $location['lng']; # => -122.6764816

Properties address, lat and lng should exist in the decoded object, but may be empty.

Kirby creator Bastian Allgeier recently created the Geo Plugin, which is a great toolkit for working with coordinates. Check it out!

:deciduous_tree: