Grav Google map Plugin

This plugin generates HTML Google map object(s) based on specific markers in the markdown document.

About

googlemaps is a plugin for Grav. This readme describes version 1.0.0. The plugin recognizes special marker(s) in a Markdown document. It replaces these with HTML Google map object(s). Each Google map object is generated by using Google's Google maps API.

The marker's syntax is [GOOGLEMAPS:<tagid>]. The <tagid> distinguishes different Google maps objects in a single HTML page from one other. With each <tagid> correspond some Grav page header settings to customize the Google map object. This screen dump illustrates how this might look like:

 (it's taken from my [website](https://aptly.io/about/hiking))

Issues

Please open a new issue or request here if you have troubles.

Known issues and workarounds

• Since June 2016 Google insists on the use of their API key for accessing their services. Request the key through the Google API console. Store the key in your googlemaps configuration file (user/config/plugins/googlemaps.yaml). The example key in the following snipit is a dummy. Don't disclose your real key to others (pay attention when using a public github repo):

    apiKey: Fkldf89eS_jkKyHuq_fklEfdfFqO73KlK1i7vz4
  

• Doesn't the map show up while you're sure that all is configured properly (e.g. the same set-up worked for an previous googlemaps plug-in version)? Some themes' templates are not completely up-to-date with the latest grav-core. These typically miss the following twig source:

    {% block bottom %}
        {{ assets.js('bottom') }}
    {% endblock %}
  

  Please kindly ask the theme's original author to add assets.js('bottom') by referring to this plug-in and Grav's reference theme antimatter; more specifically here.

• Grav's modular sub-pages have a limitation related to header assets for the modular sub-page (see #562). When placing a googlemap on a sub modular page, as a workaround:

  1. Prevent the loading of the css asset as follows:

     googlemaps:
         built_in_css: false
     

    2. Instead add the css directly into the sub modular page with this style
(of course; before the actual marker):
        ```
        <style type="text/css">
            .googlemaps_container {
                position: relative;
                width: 100%;
                padding-bottom: 50%;
            }
            .googlemaps {
                position: absolute;
                width: 100%;
                height: 100%;
            }
        </style>
        ```

- There's a defect with a modular sub-page that has a ```googlemaps.enabled = false``` configuration;
it erases the Google maps assets of its earlier sibling modular sub-page(s).
The obvious workaround is to remove (e.g. comment out) the googlemap configurations
on any modular sub-page instead of using the ```googlemaps.enabled = false```.
(The root cause is that the enabled flag is seen globaly).


## Installation and Updates

The Google maps plugin can be installed in 3 ways:

1. There's a manual install and update method by downloading
[this plugin](https://github.com/aptly-io/grav-plugin-googlemaps)
and extracting all the plugin's files in `</your/site>/grav/user/plugins/googlemaps`.
Note that a `git clone https://github.com/aptly-io/grav-plugin-googlemaps` does the trick as well.

2. Use the `bin/gpm install googlemaps`

3. Use the admin plugin as a user with admin rights.


## Usage

The plugin comes with a sensible and self explanatory default plugin configuration
(except for the Google API key!).
Each page containing the `[GOOGLEMAPS:<tagid>]` marker can include  a `<tagid>`
specific configuration to further customize the Google map with:

  - [marker(s)](https://developers.google.com/maps/documentation/javascript/markers)
  - [KML data layer](https://developers.google.com/maps/tutorials/kml/)

Each Google maps object corresponds with a unique `<tagid>` to render correctly.
For modular sub-pages, as these are joined into one single page,
make sure these `<tagid>` are all different as well!

The map's width is 60% of the window (and the height is proportional to this width)
(see the asset `googlemaps.css`).


### Operation of the plugin

1. The plugin searches for the `[GOOGLEMAPS:<tagid>]` markers.
1. It extracts the configuration in the page header that corresponds with the `<tagid>`.
1. _Each_ marker is replaced with
   - a `<div id="<tagid>"></div>`
   - a global JavaScript snippet that calls a helper function
     `initGoogleMaps(<tagid>, <configuration for the specific tagid>)`</br>
     The helper function uses the Google map API to do the real work:
     instantiate the googlemaps object inside the foreseen `<div>`
     according to the configuration.


### Configuration Defaults

#### These go in `user/config/plugins/googlemaps`:

If you need to change any value from its defaults,
then the best approach is to copy the modified version of the
[googlemaps.yaml](googlemaps.yaml) file into your `users/config/plugins/` folder.
This overrides the default (system wide) settings.

When setting `enabled` to `false` for a specific page,
this plugin still removes its specific `[GOOGLEMAPS:<tagid>]` markers to avoid that
these (ugly) markers end up in the HTML output.

Global plugin (and per-page) configurations

enabled: true # Set to activate this plugin built_in_css: true # Use the plugin's asset googlemaps.css apiKey: Fkldf89eS_jkKyHuq_fklEfdfFqO73KlK1i7vz4 # a dummy! Get your own @google API console

#### Specific per page (and map) settings

Let's use the earlier [screen dump](#screendump ) to describe the configuration

The following markdown content example contains 2 markers (with `tagid`s: `track_01` and `track_02`)
```markdown
#### A 15km trip
[GOOGLEMAPS:track_01]

To give you an idea of the scenery:

<a name="treasures">
![hidden treasures](trail_nextto_railway_scl10.png)
</a>

#### A 12km trail
[GOOGLEMAPS:track_02]

These tagid appear in the Grav page header under the googlemaps setting. This allows customization as annotated in the earlier screen dump.

googlemaps:
    track_01:
        center: 51.009314, 4.061254
        zoom: 12
        type: TERRAIN
        kmlUrl: https://aptly.io/user/pages/02.about/02.hiking/track_01.kmz
        kmlStatus: true
        markers:
            - location: 51.009358, 4.061578
              title: The local church
              zIndex: 1
              timeout: 1000
              info: <strong>The local church</strong>.<br/>Cleaned up in recent years!
            - location: 51.017227, 4.073198
              title: A secret passage
              zIndex: 2
              timeout: 2000
              icon:  https://aptly.io/user/pages/02.about/02.hiking/trail_nextto_railway_thumbnail.png
              link: "#treasures"
    track_02:
        center: 51.009314, 4.061254
        zoom: 12
        type: TERRAIN
        kmlUrl: https://aptly.io/user/pages/02.about/02.hiking/track_02.kmz
        scrollwheel: false

Explanation

• center defines the map's latitude/longitude center.
• zoom sets the map's zooming (scale) factor.
• type holds the map's type. Possible values are TERRAIN, ROADMAP, HYBRID and SATELLITE.
• kmlUrl points to KML data. It's rendered over the map. Here the KML is exported (as KMZ; a compressed KML format) from the My Tracks Android application and copied on the website. Note that Google no longer supports the mytracks application (they became the new M$).
• kmlStatus is false by default. Enabled it for clues in case the KML layer is not showing up properly.
• markers is an array of markers. Each marker support these settings:
  • location defines the marker's location on the map. It's the only mandatory setting.
  • title is text that shows up when hovering over the marker.
  • zIndex gives a z order value to the marker (making it appear before or after other markers).
  • timeout delays the drop down animation of the marker. Fancy when multiple markers have different delays.
  • info is the content of a pop-up when clicking the marker. It's mutual exclusive with the link option. As illustrated, Google map API supports HTML markup inside this info.
  • icon points to a custom marker image.
  • link holds the URL that's triggered when clicking the marker. It's mutual exclusive with the info option. Put page local references in quotes to avoid that the # is taken as a YAML comment.

Additional configuration

Each Google map object has these additional properties (not illustrated in earlier's example):

• apiKey: if using a Google API key. If one has been using the Google service before (June 2016) from the website, an API key is not necessary according to Google.
• backgroundColor: for a background colour (e.g. match this with your web-site's background or main colour) while the map is building up.
• disableDefaultUI: false disables the default UI controls.
• disableDoubleClickZoom: false disables zoom/center on a double click.
• draggable: false disables dragging the map (associated customization options draggableCursor and draggingCursor are mutual exclusive with this option).
• draggableCursor: the name or url of the cursor to display when mousing over a draggable map.
• draggingCursor: the name or url of the cursor to display when the map is being dragged.
• keyboardShortcuts: false prevents map control with the keyboard, enabled by default.
• mapTypeControl: false disables the map type control.
• mapTypeControlOptions: map type look and feel e.g. {style: 2, position: 11} for a DROPDOWN_MENU at bottom center. Please consult Google map's documentation.
• maxZoom: maximal zooming.
• minZoom: mininmal zooming.
• scrollwheel: false prevents accidently zooming the Google map object while scrolling through the web page with the scrollwheel.
• streetViewControl: false disables the street view peg man (e.g. for maps without street road overlay).
• streetViewControlOptions: the streetview look and feel e.g. { position: 11}.
• zoomControl: false disables the zoom control.
• zoomControlOptions: the zoom control look and feel e.g. { position: 11}.
• controlStyle: set to azteca to enable the retro Google maps control look.

Development

A few notes on hacking the Google maps plugin.

The free IDE Netbeans is used for editing and debugging Grav and the googlemaps.php plugin code. The free code editor Visual Studio Code (VS Code) was used for editing googlemaps.ts. The TypeScript file was compiled into Ecmascript 5.0 as googlemaps.js with the tsc compiler through VS Code.

These commands install the necessary tools and then transpile and minify the googlemaps.ts into its `googlemaps.min.js (in case you'd like to modify):

cd user/plugins/googlemaps
npm install # will install gulp and its dependencies defined in included `package.json`
export PATH=node_modules/.bin:$PATH     # include these biuld tools in the PATH
gulp        # runs the default task in gulpfile.js: minifying the js source

Use system.debugger.enabled to toggle back to the normal (not minified) googlemaps.js to debug in the browser.

License

Copyright 2015, 2016 Francis Meyvis.

Licensed for use under the terms of the MIT license.