Insert a dynamic Google Map into wiki pages

Description

This macro lets the user insert a full dynamic ​Google Map. Because a Google map uses Javascript, a ​compatible browser is needed. Newer versions of Firefox and MS Internet Explorer are compatible.

For Javascript-less static maps, use the similar GoogleStaticMapMacro.

Multiple Google Maps on the same wiki page are supported.

The macro should work both with Trac 0.11 and 0.12. There is only a 0.11 directory which can also be used for Trac 0.12. The AdvParseArgsPlugin is used to allow for quoted argument values and must also be installed.

The recent version ([4801]) of this macro needs the AdvParseArgsPlugin in revision [4795] or later.

Feedback: I would like to get some user feedback for this macro. Tell me if you like it or not and what could be better. Feel free to request additional features as long they are supported by the ​Google Maps API by opening a feature request.

Bugs/Feature Requests

Existing bugs and feature requests for GoogleMapMacro are here.

If you have any issues, create a new ticket.

defect	2 / 3
enhancement	1 / 2

ToDo/Planned

• Implement some error handling for driving directions.
• Default values in config file for all arguments.
• Maybe merge source with GoogleStaticMapMacro to allow addresses there, too.
• Argument static=yes to render a static map while using GoogleMapMacro format.

Download

Download the zipped source from here.

The plugin is also available on ​PyPI.

Source

You can check out GoogleMapMacro from here using Subversion, or browse the source​ with Trac.

There is a development version which can be unstable in some configurations: check-out.

Installation

This macro is now provided as a Python package.

AdvParseArgsPlugin must be installed to run this plugin.

If you have installed an older single-file version of the macro, please remove it from the plugins directory and note the different component name (see below).

Configuration

A different ​Google Map API key is needed for every web domain, which can be obtained for free from Google. Please check if the Google Map API Terms of Use apply to your Trac project. They apply to free and openly accessible Trac projects.

To enable the macro put the below text into your trac.ini file, which is located in the config directory of your Trac installation. You can define project wide default values for some arguments and also whether the geocoding (address-to-coordinates conversion) is done on by the Trac server or by the client's web browser.

Google recommends server side geocoding with caching which is now implemented and can be enabled using geocoding = server. Please note that this creates a table googlemapmacro in your Trac database which is used for the caching. Server side geocoding is recommended but disabled by default.

You need to restart Trac to reread the macro file and the configuration file. If you select server side geocoding you also need to update the Trac database using trac-admin <trac path> upgrade.

[components]
tracgooglemap.* = enabled

[googlemap]
api_key = <Your Google API key (long hex number)>
## Server side geocoding (address-to-coordinates conversion) incl. caching (recommended).
## Please note that this creates a table 'googlemapmacro' in your trac database.
## Possible settings are 'server' or 'client' (without the quotes). Default is 'client' to inadvertently prevent changing the database.
#geocoding = server
## Optional default settings, e.g:
#default_size = 400x400
#default_zoom = 6
#default_target = newwindow

Usage

The macro knows the following arguments, which can be used in the normal key1=value1, key2=value2,... syntax. If a value includes one or more commas, then it must be set in double quotes (" "). If a key-less value is given, it will be taken as center coordinates if it is in the proper format, otherwise it is taken as an address. Unknown (or misspelled) keys or key-less values except the first are silently ignored.

address

Sets the center of the map to the given address. The value must be surrounded by quotes if it includes commas, e.g. "Street, City, Country". If an address but no zoom value was given an appropriate value will be guessed based on the address accuracy returned by Google. At the moment this isn't very accurate but soon ​Google might improve this.

center

Sets the center of the map to the given coordinates. The format is {latitude}:{longitude} or "{latitude},{longitude}".

zoom

Sets zoom factor. Allowed values are between 0 (whole world) and 19 (single house). High zoom values might not be supported by Google Maps for all parts of the world.

size

The size either in the format {width}x{height} as numbers in pixel: 300x400 means 300px wide and 400px high or in the format {width}{unit}:{height}{unit}, where unit can be any CSS unit (em, ex, px, in, cm, mm, pt, pc).

types (optional)

Sets the map types selectable by the user, separated by colons (:). If it is not given, then the standard types of Google Maps are used (Normal, Satellite, Hybrid). The following types are available (values are case-insensitive):

• normal: Normal street-map
• satellite: Satellite picture
• hybrid: Satellite picture with streets as overlay
• physical: Terrain map

type (optional)

Sets the initial map type. See the types argument for the available types. If this argument is not given, then the first listed type under types is used initially.

controls (optional)

Sets the used map controls. Multiple controls can be given, separated by colon (:). The value is case-insensitive. If not set, then the controls MapType and LargeMap are used. If set but empty no controls are displayed. The following controls are available (descriptions taken from the ​Google Map API page):

• LargeMap: Control with buttons to pan in four directions, and zoom in and zoom out.
• SmallMap: Control with buttons to pan in four directions, and zoom in and zoom out, and a zoom slider.
• SmallZoom: Control with buttons to zoom in and zoom out.
• Scale: Control that displays the map scale.
• MapType: Standard map type control for selecting and switching between supported map types via buttons.
• HierarchicalMapType: Drop-down map type control for switching between supported map types.
• OverviewMap: Collapsible overview mini-map in the corner of the main map for reference location and navigation (through dragging).

marker

(New) Allows the user to set labeled markers on given location of the map. The format for a marker is {latitude}:{longitude};{Letter};{TracLink};{Title} or "{Address}";{Letter};{TracLink};{Title}. If the string 'center' is used instead of an address the center of the map is marked. The optional marker letter can be either A-Z or 'o', '.' or empty for a plain marker. An optional TracLink can be given which may be opened in a new window (see target) when clicked on the marker. An optional marker title can be set which will get displayed when the mouse cursor is over the marker. From revision [4801] on multiple markers can be given which replaces the markers argument.

markers

(Old) Can be used to set multiple markers which are are separated using the | character. Optional values can be kept empty, e.g.: "{Address}";;;My Address would display the address with the title 'My Address'. Trailing semicolons can be skipped. Addresses, links and titles which include either ,, ; or | must be enclosed in double quotes (" ").

target

If set to new or newwindow all hyperlinks of the map markers will be opened in a new window (or tab, depending on the browser settings) or in the same window otherwise.

from,to

Request driving directions from -> to. Multiple to addresses are allowed. No address or center need to be given.

Processor Syntax

While Tracs normal macro syntax ([[Macro(key=value,key=value)]]) is nice for smaller arguments lists it is getting messy for longer lists. This macro now also supports the so called wiki processor syntax ({{{ <linebreak> #!Macro <linebreak> content <linebreak> }}}) to allow for multiple lines of arguments.

In this case a line break will be read as a comma:

{{{
#!GoogleMap
key1=value1
key2="value 2, with comma"
key3=value3, key4=value4
}}}

is identical to:

[[GoogleMap(key1=value1,key2="value 2, with comma", key3=value3, key4=value4)]]

Examples

Using geographic coordinates

Please use a colon, not a comma, as separator for the coordinates:

[[GoogleMap(center=50.0:10.0, zoom=10, size=400x400)]]
or
[[GoogleMap("50.0:10.0", zoom=10, size=400x400)]]
or
[[GoogleMap(50.0:10.0, zoom=10, size=400x400)]]

Using an address

Please use semicolons, not commas, as separators in the address:

[[GoogleMap(address="Street, City, Country", zoom=10, size=400x400)]]
or
[[GoogleMap("Street, City, Country", zoom=10, size=400x400)]]
or, if you really want to:
[[GoogleMap(Street; City; Country, zoom=10, size=400x400)]]

Please note that the address is converted into coordinates by user-side Javascript every time the wiki page is loaded. If this fails, then no map will be shown, only an empty gray rectangle.

Server side address conversion including caching is underway.

Using both geographic coordinates and addresses

If both address and center coordinates are given, then the result depends on the `geocoding` setting:

server

The address is resolved on the Trac server and the coordinates are completely ignored.

client

The map is first centered at the given coordinates and then moved to the given address after (and if) it was resolved by the client-side JavaScript code.

[[GoogleMap(center=50.0:10.0,address="Street, City, Country",zoom=10,size=400x400)]]

Select Map Types

To show a map with the standard map types where the satellite map is preselected:

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, type=satellite)]]

To only show a satellite map (please note the added 's'):

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, types=satellite)]]

To show a map with hybrid and satellite map types (in this order) where the satellite map is preselected:

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, types=hybrid:satellite, type=satellite)]]

To show a map with hybrid and satellite map types (in this order) where the hybrid map is preselected:

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, types=hybrid:satellite)]]
or
[[GoogleMap("Street, City, Country", zoom=10, size=400x400, types=hybrid:satellite, type=hybrid)]]

Markers

To create three markers: one at the center of the map (A), one at the next street (B) and one at coordinates 10.243,23.343 (C):

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, markers=center;A|"Next street, City, Country";B|10.243:23.343;C)]]

The same with hyperlinked markers:

[[GoogleMap("Street, City, Country", zoom=10, size=400x400, markers=center;A;wiki:MyWikiPage|"Next street, City, Country";B;ticket:1|10.243:23.343;C;http://www.example.com/)]]

Recent Changes

17140 by rjollos on 2018-04-16 20:16:26

TracGoogleMapMacro 0.6: Fix unintended name change

17139 by rjollos on 2018-04-16 20:14:38

TracGoogleMapMacro 0.6: Conform to PEP8

15265 by rjollos on 2016-02-11 04:29:08

Remove unnecessary svn:mime-type on js and html files

svn:mime-type was set to "plain" for many files.

(more)

Author/Contributors

Author: martin_s
Maintainer: Martin Scharrer
Contributors: