On this page… (hide)
Embedding a Google map is one way for a web site to speak to its visitors. However, generating a Google map is a complex ordeal made slightly more difficult when using a wiki to manage site content. The Google Map API is a recipe for PmWiki that helps the site editor seamlessly make and maintain a Google map on the site. This is accomplished by using an integrated suite of PmWiki directives which allows editors to mark points, make lines, and tie a link to a point on the map. The result is a simple way to use Google's powerful map protocol on a PmWiki site.
The user-contributed commentary and notes regarding this recipe are found on the Google Map API Discussion page.
Install the Script. The first step in the installation is to
download Δ and install the
software. To place the files in their proper location, extract the files
in the parent directory of both the /pub and /cookbook
directories (usually $FarmD/cookbook directory, the javascript in the
/pub/scripts directory, and images in /pub/images/gma directory.
If you plan on using the ZIP code function, you will also want the
ZIP code source file Δ—the source file is
placed in path/to/GoogleMapAPI/library.
Configure the Site. After the code is installed, you will need to configure the site. This is typically done in the local/config.php file, so this How-To assumes an installation using the file. Before the site is configured, however, you will need to obtain a Google map site key. You will need a unique key for each distinct web site. Google does not provide its interface to sites without this key.
In the configuration file (local/config.php), you must set one
variable: $GmaKey. Beyond that, you may set other values using
$GmaDefaults as discussed below. These values should be set before
the recipe is called. Most of these defaults may be overridden via the
directives.
Once the variables are set, you will need to include the recipe (e.g.
"require_once('path/to/cookbook/gma-2.2.0-pre2.php);"). This command
must follow the $GmaKey and $GmaDefaults variable declarations.
Configure the Skin. One variable, $GmaIEFix must be embedded
The $GmaIEFix variable must be placed within the leading <html>
tag (e.g. <html$GmaIEFix>) to offset a separate browser bug. (Oddly
enough, both bugs are Internet Explorer-based.) Additionally, you may
want to set a CSS value for the default DIV tag (e.g. @@<div
id='map'>@@) in that skin. This is not required as the recipe sets
default values, but it may be desired.
Notice: This recipe now uses $HTMLFooterFmt, which was added
to PmWiki in release 2.1.16. Please upgrade your PmWiki.
Add map generating markup. Add the markup to the page you want the map to appear, with all relevant options.
Using this recipe is fairly straight forward. There are three types of map tools available: point, line, and map. The map tool must be used to generate the map. Either the point or the line must also be used, and these types may be mixed. We will take each map tool in turn, beginning with the map tool.
Using the Map Tool. The map tool (:gma-map [options]:) generates the map itself. The map is located where the
directive is placed on the wiki page. Specifically, the map tool returns
an empty DIV statement which the Google software uses to embed the map.
This recipe automatically centers and zooms the map based on the points
and/or lines contained within the map. The map tool provides several
options which help control the use of the map. Each of these options may
be configured by the site administrator, or set by the editor for a
specific map. These options include:
Example:
(:gma-map width='80%' ctrl=small,-type:)
This example changes the width to 80 percent of the wikitext element. It also changes the default map controler from large to small and removes the map type controller. Additionally, by not setting the zoom setting (e.g. zoom=5), the recipe automatically zooms out enough that all points in the map are visible.
Using the Point Tool. The point tool (:gma-point lat lon [options]:)
places a marker at the designated spot. The location is determined by
latitude and longitude settings. Additionally, the point can contain a
link and/or text. (Coming soon) Finally, the marker look can be
determined using the icon option. The options include:
Example:
( :gma-point lat=55.0 lon=-85.0:) ( :gma-point lat=56.0 lon=-84.0 text='Take me away to that special place.':) ( :gma-point lat=53.0 lon=-84.0 link='in text link':) ( :gma-point lat=57.0 lon=-83.0 note='No directions to this point.':) ( :gma-point zip=22202 text='The U.S. Capitol ZIP code':) ( :gma-point addr='5 Connell Drive, Little Rock, Ar, 72205':)
This example places several points on the map. The first point demonstrates the minimum necessary to create a point. Alternatively, the ZIP could be used. The second point demonstrates adding an information window to a point. The third point demonstrates creating a link between the point and page text. The fourth point demonstrates adding an information window to a point without directions. The fifth point demonstrates the use of the ZIP feature (only in the U.S.). The last point demonstrates the use of the address lookup feature.
Using the Line Tool. The line tool (:gma-line lat lon [options]:)
generates color-coded lines drawn by a series of
line-points. Each line-point along the line is described using this
markup. The location of each is determined by latitude and longitude
settings.
Example:
( :gma-line id=1 zip=90210:) ( :gma-line id=1 zip=72076:) ( :gma-line id=1 zip=22207:) ( :gma-line id=2 lat=24.0 lon=-50.0 color='#990000' opacity=50:) ( :gma-line id=2 lat=-10.0 lon=-60.0:) ( :gma-line id=2 lat=20 lon=-90:)
These are two examples of lines on a map. The first line uses ZIP codes and accepts the default color, line width and opacity. The second line uses standard latitude and longitude (lat and lon respectively). However, the second line changes the color to maroon and reduces the opacity to 50 percent. To have markers or information windows on a line, a point should be generated (using (:gma-point:)) with that information.
The Google Map API may have site-administrator configured variables. The
controlling variable is the $GmaDefaults array. For easy reference,
the defaults are displayed as an HTML comment before the controlling
Javascript. Values that the site administrator may set include:
Example:
## This adds the Google map cookbook recipe
$GmaKey = 'ABQIAAAAFm14TvnIWud_4d60iCe7qhS79cqvLo7-6vkZ4NhKaD9LTYosFRTZOemEIUx93RaOqn8DsD8j1eqiew';
include_once('cookbook/GoogleMapAPI/gma-2.2.0-pre2.php');
This first example shows the bare minimum necessary to establish a Google Map. The $GmaKey is used to tell Google that the site is registered to use the map. The include_once() (alternatively is require_once()) adds the recipe to the site.
$GmaDefaults['ctrl'] = 'overview,small'; # Allows the overview box and small controls. $GmaDefaults['view'] = 'hybrid'; # Map initially displays in hybrid mode. $GmaDefaults['width'] = '80%'; # Map will spread to 80 percent of the map.
This set of $GmaDefaults variable settings changes the recipe
default settings. Specifically, the first line ('ctrl') defines which
controls are provided by default. The second line ('view') changes the
map view from normal to hybrid. The third line ('width') changes the
width of the map via CSS. The page editor can set map-specific
settings for each of these defaults.
See Cookbook:GoogleMapAPI#release for more release history.
For a complete list of past entries, check out the journal page.
Copyright (c) 2006, Benjamin C. Wilson. All Rights Reserved. You have permission to use this software for web site use provided this copyright statement remains intact. You may not otherwise republish this software without prior permission of the author.
[[!Projects]] [[!PmWikiRecipe]]Technical
Copyright © 1997-2010 Benjamin C. Wilson · All Rights Reserved.