====== googlemaps3 Plugin ======
---- plugin ----
description: Google Maps Plugin for Google Maps API Version 3
author : Bernard Condrau
email : bernard@condrau.com
type : syntax
lastupdate : 2021-05-12
compatible : Hogfather+
depends :
conflicts :
similar : googlemaps, googlemap3, maplink, openlayersmap
tags : maps
downloadurl: https://github.com/thalueng/dokuwiki-plugin-googlemaps3/archive/refs/heads/main.zip
bugtracker : https://github.com/thalueng/dokuwiki-plugin-googlemaps3/issues
sourcerepo : https://github.com/thalueng/dokuwiki-plugin-googlemaps3/
donationurl:
screenshot_img : https://wiki.condrau.com/_media/google:dokuwiki_googlemaps3_plugin.png
----
===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
===== Overview =====
There are a number of different maps and google maps plugins available, all of which are outdated or limited in their usage, so I wrote a new one which can easily be extended should you miss a feature. This was originally based on Christopher Smith's googlemaps plugin, but with a complete overhaul, additional features, and changes in syntax.
You need to have a //Google Maps API key// to use this plugin (see [[plugin:googlemaps3#configuration_and_settings|Configuration and Settings]])
===== Features =====
* Place one or more google maps on a wiki page
* Set markers on the page with customized icon and popup
* Select text, image, and directions link to show in marker popup
* Choose language of google maps user interface
* Customize the controls visible on the map
* Maps and markers can be defined by latitude/longitude coordinates or address
* Alternatively display a map with KML or GeoRSS Layers
===== Examples/Usage =====
See the plugin in action [[https://wiki.condrau.com/google:api|here]], created with the following syntax:
address,hua hin beach,Hua Hin Beach,beach.png,Hua Hin Beach with Hilton Hotel,Directions,_media/google:hua_hin_beach.jpg
The same can be achieved with:
12.57076,99.96260,Hua Hin Beach,beach.png,Hua Hin Beach with Hilton Hotel,Directions,_media/google:hua_hin_beach.jpg
===== Syntax =====
[marker1]
[marker2]
[...]
[markerN]
==== Map syntax ====
^ Option ^ Setting ^ Default ^ Default set in ^
| lat | Latitude of map center | 12.57076 | Plugin1 |
| lng | Longitude of map center | 99.96260 | Plugin1 |
| address | Google Maps location address3 | | Plugin1 |
| zoom | Initial zoom level of map | 0 | Plugin1 |
| type | Google Map Type5 | roadmap | API2 |
| width | Width of map | 100% | style.css |
| height | Heigth of map | 500px (must be fixed height) | style.css |
| language | Language of user interface | en | API24 |
| region | Region Bias6 | US | API24 |
| disableDefaultUI | Disable all map controls | 0 (false) | API2 |
| zoomControl | Enable zoom control | 1 (true) | API2 |
| mapTypeControl | Enable map type control | 1 (true) | API2 |
| scaleControl | Enable scale control | 1 (true) | API2 |
| streetViewControl | Enable street view control | 1 (true) | API2 |
| rotateControl | Enable rotate control | 1 (true) | API2 |
| fullscreenControl | Enable fullscreen control | 1 (true) | API2 |
| kml | Add KML or GeoRSS layer7 | off | Plugin1 |
=== Table notes ===
- Default set in syntax.php where no default is set in API
- Default set in syntax.php corresponding to API default
- Map will pan to location address if given and exist after having been centered to lat/lng coordinates
- Default for all maps set in Plugin Configuration, can be overridden for each wiki page (must be set for first map on the page, and cannot be changed for other maps on the same page)
- Available map types: roadmap, hybrid, satellite, terrain
- Region Bias where google maps leans towards (example: location address of 'Freiburg' will center the map in //Freiburg/Germany// if region is set to **US** or **DE**, but will center to //Freiburg/Switzerland// if region is set to **CH**)
- URL to kml file which includes markers or overlays
=== Notes ===
- Map **Option** identifiers are case-sensitive
- coordinates and initial zoom factor are mandatory (but can be taken from default), all other options are optional
==== Marker syntax ====
lat, lng, title, icon, info, dir, img, width
^ Option ^ Setting ^ Default ^ Shows as/in ^
| lat | Latitude of marker1 | 0 | Marker |
| lng | Longitude of marker1 | 0 | Marker |
| title | Title of marker2 | | Hover, Popup |
| icon | Custom icon as image file or svg path3 | | Marker |
| info | Info text4 | | Popup |
| dir | Directions link text5 | | Popup |
| img | Image URL6 | | Popup |
| width | Width of popup7 | 200px | Popup |
=== Table notes ===
- Used to place the marker on the map. If lat is given as //address//, then lng is interpreted as address. See [[plugin:googlemaps3#examples_usage|Examples/Usage]] above.
- The title shows when hovering over the marker, and as first line in the popup window.
- If icon is a
* 'filename' with extension, then the folder path for custom marker icons is prepended and the selected custom marker is put on the map. Custom markers show on the map irrespective of the zoom level, where google maps standard markers only show on selected zoom levels.
* 'identifier' without file extension, then it's interpreted as svg path which needs to be defined somewhere else on the page as javascript variable, for example as part of a library or template.
- The text can include wiki markup.
- This text shows in the marker popup and, when tapped or clicked, opens a new google map page with the marker location as destination
- If specified, then the image from the provided URL will be included in the marker popup window between title and info text.
- Default popup window width is specified in the plugin's style.css file, but can be overridden per marker here.
=== Notes ===
- You can skip options which are not needed, but you need to keep sequence and position of options. To display a marker with standard icon and popup window, for example, you would define the marker like so:address,hua hin beach,Hua Hin Beach,,Hua Hin Beach with Hilton Hotel
- The delimiter (default=',') can be configured in the plugin configuration.
- You can place as many markers in a map as you wish, each marker must have its own line and be the only information on that line.
- The googlemaps3 plugin ships with a number of custom png icons like //beach.png// used in [[plugin:googlemaps3#examples_usage|Examples/Usage]]. I have included a simple php file which displays all icons in the package, and when hovering over an icon the icon file name is shown. Use the following URL after having installed the plugin (/lib/plugins/ must be accessible from the web):https://your.wiki.domain/lib/plugins/googlemaps3/icons/icons.php
===== Configuration and Settings =====
==== Google Maps API ====
* Log in to [[https://console.cloud.google.com/google/maps-apis/overview|Google Cloud Platform]]
* Register an API Key and enable //Maps JavaScript API// in [[https://console.cloud.google.com/google/maps-apis/api-list|Enabled APIs]]
* If you want to use addresses instead of coordinates you also need to enable the //Geocoding API//
==== Plugin Configuration ====
The following options set the plugin's behavior for your site unless overriden per map or page.
^ Option ^ Purpose ^ Default ^ Override possible ^
| key | Google Map API key | | no |
| region | Region Code Biasing | US (Google Maps API) | per page |
| language | Language of Google Maps UI | Browser language (Google Maps API) | per page |
| path | Path to customized icons | lib/plugins/googlemaps3/icons/ | yes, if empty1 |
| delim | Delimiter used for markers2 | '','' | no |
=== Table notes ===
- Access a marker icon with 'lib/plugins/googlemaps3/icons/beach.png' instead of 'beach.png' when the path **Option** is set to an empty string.
- Change to a delimiter you do not need in any of your marker titles or popup strings.
==== CSS ====
Default plugin style sheet:
/* maps */
.googlemaps3 {
width: 100%;
height: 500px;
}
/* marker popup */
.googlemaps3.markerinfo {
width: 200px;
height: auto;
}
=== Note ===
* You can add 'width' and 'height' options for each map.
* You can add 'width' option for each marker.
* You can add CSS styles for individual maps and markers on a page. Every map and marker on the page is numerated with an ID, //#googlemaps3map1..N// for maps and //#googlemaps3marker1..N// for markers. Example: on a page with 3 maps which each has 2 markers, the 2nd Map's CSS and the 2nd Marker's CSS of that map would be styled like this:
#googlemaps3map2 {
height: 400px;
}
#googlemaps3marker4 {
width: 300px;
}
===== Change Log =====
=== 2021-05-12 ===
* Initial release