[[TOC]] = Insert a static Google Map as image = == Description == This macro uses the [http://code.google.com/apis/maps/documentation/staticmaps/ Google Map API] to include '''static''' images of maps. '''Static''' means that is is only a simple image without any user interaction not the usual feature-rich dynamic map on http://maps.google.com/. The positive side is that no javascript is needed to display the map image. For a dynamic Google map use the GoogleMapMacro. Please note that the maximum size supported by Google is 640x640 pixels. If a bigger width or height is requested it will be reduced to 640px. The macro should work both with Trac 0.11 and 0.12. At the moment 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. == Bugs/Feature Requests == Existing bugs and feature requests for GoogleStaticMapMacro are [report:9?COMPONENT=GoogleStaticMapMacro here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=GoogleStaticMapMacro&owner=martin_s new ticket]. == Download == Download the macro as [download:googlestaticmapmacro/0.11 ZIP-file]. == Source == You can check out GoogleStaticMapMacro from [http://trac-hacks.org/svn/googlestaticmapmacro here] using Subversion, or [source:googlestaticmapmacro browse the source] with Trac. == Installation & Configuration ==#config Install the plugin [http://trac-hacks.org/#HowdoIinstallthesethings as usual]. To enable the macro put the following into your `trac.ini` file, which is located in the `config` directory of your trac installation. You need to restart trac to reread the macro file and the configuration file. {{{ [components] tracgooglestaticmap.* = enabled [googlestaticmap] api_key = # not required for API v2 # Optional settings: #default_size = 300x300 #default_language = de #default_api_version = <1 or 2> # should be 2 for newer installations. Set to 1 if you want to keep older macros unchanged }}} == Upgrade from older Versions ==#Upgrade The current version of the macro uses the [http://code.google.com/apis/maps/documentation/staticmaps/ Google Static Map API v2], while older versions used [http://code.google.com/apis/maps/documentation/staticmaps/v1/ API v1] ([http://code.google.com/apis/maps/documentation/staticmaps/upgrade.html Upgrade guide]). The syntax provided by Google has changed between the API versions. In order to provide the newer features but also not break existing macros both API versions are supported using the `api` key. The older syntax can still be used with newer versions of the macro by setting `api=1` either as a macro argument (`[[GoogleStaticMap(api=1,)]]`) or using the global [#config configuration] option `default_api_version`. Please note, that since v2 an API key is not required anymore by Google. The API v1 still requires a trac server specific Google Map API key which is [http://code.google.com/apis/maps/signup.html provided by Google for free]. == Usage & Examples == This documentation describes the syntax for the macro v1.x which uses Google's API v2 (see [#Upgrade]). The older syntax is still supported using the `api=1` argument. See [./GoogleStaticMapMacro?version=18 an older version] of this wiki page for the old syntax. Mixing of older and newer syntax is not supported. === Parameters === The macro accepts the official [http://code.google.com/apis/maps/documentation/staticmaps/#URL_Parameters Google Static Map argument (see there)] as well as a few internal arguments: title:: Sets the HTML title of the map image. api:: Sets the API version to be used. By default set to "`2`". To reuse the older macros set `api=1` as mentioned earlier. key:: Sets the API key if not set globally in the config file. Deprecated for macro v1.x / Google API v2. All map locations (center, markers, path) can now be given as address or geographic coordinates (latitude,longitude). Please note that addresses and coordinates __must__ be quoted using double-quotes (`"`) when they include a comma. This is always the case with coordinates. The old macro syntax used colons (`:`) as substitutes, which no longer supported in the new syntax. For example: {{{ [[GoogleStaticMap(center="50.805935,10.349121",zoom=5,size=400x400)]] [[GoogleStaticMap(center="Germany",zoom=5,size=400x400)]] }}} will both result in the following map image: [[Image(http://maps.google.com/staticmap?center=50.805935%2C10.349121&zoom=5&size=400x400,nolink)]] === Markers === You can add markers to the static map using the '`markers`' argument. The format is '`markers=style settings|first location|next location|...`' ([http://code.google.com/apis/maps/documentation/staticmaps/#Markers details]), e.g.: `markers="size:mid|label:A|color:blue|50.805935,10.349121"`, creates a blue marker labeled with 'A' at 50.805935,10.349121. Again also addresses can be used to specify locations. The whole value must be quoted if any commas are included. Multiple `markers` arguments can be given to add markers with different styles. So, {{{ [[GoogleStaticMap(center="50.805935,10.349121",zoom=5,size=400x400,markers="color:blue|label:A|50.805935,10.349121",markers="color:green|label:B|50.000000,10.000000|Berlin,Germany",markers="color:yellow|label:C|Regensburg,Germany")]] }}} will result in the following map image: [[Image(http://maps.google.com/maps/api/staticmap?center=50.805935%2C10.349121&zoom=5&markers=color%3Ablue%7Clabel%3AA%7C50.805935%2C10.349121&markers=color%3Agreen%7Clabel%3AB%7C50.000000%2C10.000000%7CBerlin%2CGermany&markers=color%3Ayellow%7Clabel%3AC%7CRegensburg%2CGermany&hl=en&sensor=false&size=400x400,nolink)]] === Paths === Paths between locations can be added using the `path` argument which has basically the same syntax as `markers`, except different styles are supported. See [http://code.google.com/apis/maps/documentation/staticmaps/#Paths the Google documentation] for details. == 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'' (`{{{ #!Macro content }}}`) to allow for multiple lines of arguments. In this case a line break will be read as a comma: {{{ {{{ #!GoogleStaticMap key1=value1 key2="value 2, with comma" key3=value3,key4=value4 }}} }}} is identical to: {{{ [[GoogleStaticMap(key1=value1,key2="value 2, with comma",key3=value3,key4=value4)]] }}} '''Example:''' {{{ {{{ #!GoogleStaticMap center="Germany" path="Munich|Berlin|Cologne|Munich" markers="label:M|Munich" markers="label:B|Berlin" markers="label:K|Cologne" markers="label:H|color:orange|Hamburg|Hannover" markers="size:small|color:green|Mannheim|Straubing|Münster" size=250x300 }}} }}} produces: [[Image(http://maps.google.com/maps/api/staticmap?center=Germany&markers=label%3AM%7CMunich&markers=label%3AB%7CBerlin&markers=label%3AK%7CCologne&markers=label%3AH%7Ccolor%3Aorange%7CHamburg%7CHannover&markers=size%3Asmall%7Ccolor%3Agreen%7CMannheim%7CStraubing%7CM%C3%BCnster&hl=en&path=Munich%7CBerlin%7CCologne%7CMunich&sensor=false&size=250x300,nolink)]] == Recent Changes == [[ChangeLog(googlestaticmapmacro, 3)]] == Author/Contributors == '''Author:''' [wiki:martin_s] [[BR]] '''Maintainer:''' [wiki:martin_s] [[BR]] '''Contributors:'''