Recent Changes - Search:
Cookbook /

Google Map API for PmWiki

Summary: Adds Google Map API to PmWiki pages.
Version: 2.2.0-Pre9
Prerequisites:
Status: Beta (out-of-date - no longer works)
Maintainer: BenWilson
Users: +2 -1 (View / Edit)
Categories: Integration, Google
File: GoogleMapAPI-2.1.2.zipΔ (stable)
File: GoogleMapAPI-2.2.0-pre8.zipΔ (development)
File: GoogleMapAPI-2.2.0-pre9.zipΔ (development, fixed address cache, 8-March-2010)
File: gma_zip.csvΔ

Table of Contents

Abstract

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 (GMA) 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.

Comments

The user-contributed commentary and notes regarding this recipe are found on the Google Map API Discussion group.

Related Recipes Used

Share other recipes that you use in combination with this recipe.

Alternative Recipes Used

Share a recipe you use instead of this one.

Warning: There is an alternative way of supplying this recipe functionality via an iframe/embed. This is a serious security issue for use in a wiki environment. If you allow either HTML in a promiscuous environment, you allow a cracker to embed a trojan via your wiki that allows a man-in-the-middle attack. I see mention of this repeatedly on this page---it is an invitation to disaster for a promiscuous tool like a wiki. Embeds and Iframes should only be allowed in a non-browser editable tool.

Community Reviews

Write an online review and share your thoughts with other Community Members.

REVIEW TEMPLATE. Copy and paste it to the top of the review list.

* * * * A Great Idea ~ ~ ~ ~ (Your signature). Then, just start typing out.
  • 0 out of 0 people found this review helpful.

Installation

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). Otherwise, copy the contents of the two directories as appropriate. Specifically, this software should have the recipe file in the /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/GoogleMapAPI/GoogleMapAPI.php');"). This command must follow the $GmaKey and $GmaDefaults variable declarations. (An example of how the local/config.php should look is found below in the discussion on System Configuration Variables.)

Configure the Skin. There are two necessary changes to your site's skin that enable this recipe. The first corrects a bug in the Internet Explorer browser, and is placed in the <html> tag. All you need to do is add $GmaIEFix in the tag, as is shown in the following example.

Top of Skin Template: 

 <html$GmaIEFix>

The next change to your skin requires upgrading to at least PmWiki 2.1.16, because it uses $HTMLFooterFmt. The skin template needs <!--HTMLFooter--> place immediately before the </body> tag. This requirement is important to ensure the map displays in all browsers capable of running Google Maps. The following is an example of how the skin template should be adjusted.

Bottom of Skin Template: 

<!--/PageFooterFmt-->
<!--HTMLFooter-->
</body>
</html>

Add map generating markup. Add the markup to the page you want the map to appear, with all relevant options.

Using the Google Map API for PmWiki

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:

  • 'mapid' (default map): The mapid option allows the editor to determine the CSS name for the map. When the multiple-maps feature is implemented, this will allow multiple maps to be generated.
  • 'lat' (default auto): The lat option sets the point's latitude. When not set, will automatically center.
  • 'lon' (default auto): The lon option sets the point's longitude. When not set, will automatically center.
  • 'view' (default hybrid): The view option allows the editor to set the initial display of the map. There are three displays available: normal, or a traditional map view; satellite, or a map showing only a satellite image mosaic; and hybrid, or a map which overlays political and road lines over a satellite map. These displays are represented by 'nor','sat', or 'hyb' respectively.
  • 'height' (default 300px): The height option the editor to set the height of the map. This value responds to CSS values (e.g. pixels, em, pt, percent, etc.)
  • 'width' (default 500px): The width option the editor to set the width of the map. This value responds to CSS values (e.g. pixels, em, pt, percent, etc.)
  • 'ctrl' (default ): The ctrl option allows the editor to select which map controls are available to the visitor. There are () controls: maptype, large, small, and overview. As each map control may be set by the site administrator, the editor may unset a default value. The negative sign is used to unset a default value (e.g. if the default is to show the overview, then '-overview' will turn off this map control. This variable is an array and values are set in serial (e.g. "ctrl=small,-overview")
    • The maptype control allows the visitor to change the map type between hybrid, normal and satellite. If set by default, -maptype will turn this control off.
    • The large and small controls allow the editor to decide whether the zoom and pan controls are large or small. Setting the opposite will deselect the default size.
    • The overview control allows the visitor to see a small window in the lower right hand corner. This window displays a smaller-scale map of the area in the main window. If set by default, -overview will turn this control off.
  • 'zoom' (default auto (0)): The zoom option allows the editor to set a specific zoom level (range: 1-16, where 1 is the coarsest, or furthest away). When set to zero, then the API automatically zooms to include all points and line-points.

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. Finally, the marker look can be determined using the marker option. The options include:

  • 'addr' (default none): Uses Google geocoding lookup service to determine the lat/lon of a point.
  • 'lat' (default 0): The lat option sets the point's latitude.
  • 'lon' (default 0): The lon option sets the point's longitude.
  • 'zip' (default none): The zip option optionally determines the point's latitude and longitude from the U.S. Census data file (circa 1999).
  • 'link' (default none): This option creates a link between the point on the Google map and the link-text on the page. Clicking the link on the page causes this point's information window to open. Clicking the link in the information window sends the visitor to the link on the page. The link text should be quoted.
  • 'mapid' (default 'map'): The mapid option allows the editor to associate a point with a given map when there are multiple maps on a wiki page.
  • 'fromto' (default 'y'): This toggles whether directions are offered for a given point.
  • text (default none): This option creates HTML text in an information window. Clicking this point's marker causes the information window to open. The text should be quoted.
  • marker (default none): This option allows the editor to use standard Google markers (marker='[A-Z]') or Google Earth icons (marker='[2..5]:[0..63]]') (the first number is the palette, the second number is the icon).

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':)
(:gma-point lat=38.8533 lon=-77.124 marker=Q:)
(:gma-point lat=38.8533 lon=-77.124 marker='3:16':)

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 sixth point demonstrates the use of the address lookup feature. The seventh point demonstrates the use of the 'Q' marker. The final point demonstrates the use of a palette/icon marker. To use this example, the Google map must already be initiated with the gma-map line.

Example:
(:gma-map width='100%' height=500px zoom=8:)
(:gma-point lat=57.149790 lon=-2.127800 marker=X text='<b>Software Systems: Open For Business</b> <br>58 Mid Stocket Road, Aberdeen, AB15 5JB':)

This example sets the width to 100%, the height to 500px and the zoom to about 20miles per 100pixels. It also adds a single marker with the letter X in a location with a text pop-up describing an address.

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.

  • 'addr' (default none): Uses Google geocoding lookup service to determine the lat/lon of a point.
  • 'id' (default 0): The id option allows the editor to create multiple lines. When creating more than one line, the id number designates to which line the point is appended.
  • 'lat' (default 0): The lat option sets the line-point's latitude.
  • 'lon' (default 0): The lon option sets the point's longitude.
  • 'mapid' (default 'map'): The mapid option allows the editor to associate a line with a given map when there are more than one map on a wiki page.
  • 'zip' (default none): The zip option optionally determines the point's latitude and longitude from the U.S. Census data file (circa 1999).
  • 'color' (default #880088): The color option allows the editor to set the line's color. Once the color is set for a given line, it need not be designated again.
  • 'opacity' (default 2): The opacity option allows the editor to set the line's opacity, measured in percentage (e.g. 0 - 100 percent). Once the opacity is set for a given line, it need not be designated again.
  • 'thickness' (default 2): The thickness option allows the editor to set the line thickness, measured in pixels. Once the thickness is set for a given line, it need not be designated again.

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. To use this example, the Google map must already be initiated with the gma-map line.

Using the Show Tool. The show tool (:gma-show:) lists the Google Earth icons accessible with the points tool (above). This allows the editor to find the palette and icon he wants to show his mark.

System Configuration Variables

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:

  • 'ctrl' (default large, overview): The ctrl option is an array and includes the controls the site-administrator wants active by default. To turn off controls, the editor would use the -option (e.g. -overview to turn off a defaulted overview control). Works in conjunction with the map tool option ctrl.
  • 'view' (default hybrid): The view default allows the site administrator to set the default map view, which may be either hybrid, normal, or satellite. Works in conjunction with the map tool option view.
  • 'height' (default 400px): The height default allows the site administrator to set the default map DIV height. This setting uses CSS syntax (e.g. px for pixels, or percentage). Works in conjunction with the map tool option height.
  • 'width' (default 400px):The width default allows the site administrator to set the default map DIV width. This setting uses CSS syntax (e.g. px for pixels, or percentage). Works in conjunction with the map tool option width.
  • 'float' (default none): The float default allows the site administrator to designate a default position for the map by determining which side text may wrap around. To have the map on the left, set this to left, to have the map on the right, set this to right. Works in conjunction with the map tool option float.
  • 'color' (default #880088) The color default allows the site administrator to set a specific web-safe color for lines. This must comply with HTML hex color notation (e.g. either #900 or #990000 for maroon). Works in conjunction with the line tool option opacity.
  • 'thickness' (default 2) The thickness default allows the site administrator to set the default line thickness for lines drawn on the map. Works in conjunction with the line tool option opacity.
  • 'opacity' (default 70) The opacity default allows the site administrator to set the default transparency for lines drawn on the map. Works in conjunction with the line tool option opacity.
  • 'zoom' (default 0): The zoom default allows the site administrator to set a specific, default zoom level (range: 1-16, where 1 is the coarsest, or furthest away). When set to zero, then the API automatically zooms to include all points and line-points.

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.

Release Notes

  • v.2.2.0 - XXXXXXXX XX, 2007 BenWilson December 09, 2006, at 01:13 PM (Features being added pre-release).
    • Fixed (pre9) Cache for address look-ups, resolves GMA Error: No Lat/Lon or ZIP given with too many points with addr. To use this, specify in config.php a directory $GmaCacheDir = "$FarmD/cookbook/GoogleMapAPI/cache"; (e.g.) and make it writeable. Frank March 08, 2010, at 01:09 PM
    • Feature Able to "float" a map, which allows text to wrap around the map.
    • Feature Multiple maps based on 'mapid' to associate map elements (points, lines, etc.) with specific maps.
    • Feature "fromto" option allows toggling looking up directions for display windows.
    • Feature Address lookup from Google's geocoding lookup.
    • Change Per Bram's suggestion, using a GMA link scrolls the web page to the top of the map.
    • Feature Complies with RecipeCheck. BenWilson February 17, 2007, at 03:53 PM
  • v.2.1.2 - August 28, 2006 BenWilson August 27, 2006, at 03:33 PM
    • Fixed Incorrect assignment of line thickness.
  • v.2.1.1 - August 27, 2006 BenWilson August 27, 2006, at 03:33 PM
    • Fixed Incorrect reference to $GmaIEFix, pointed out by Hans.
  • v.2.1.0 - August 26, 2006 BenWilson August 26, 2006, at 03:33 PM
    • Change Now possible to center the map via the (:gma-map:) interface using either zip or lat/lon options.
    • Change Deprecated $GmaScript, $GmaJs, $GmapJs. Recipe now works with 2.1.16, which has the $HTMLFooterFmt.
  • v.2.0.1 - August 23, 2006 BenWilson August 23, 2006, at 03:33 PM
    • Fixed Per Hans' observation, $PubDirUrl changed to $FarmPubDirUrl
    • Fixed The zoom configuration was enabled.
    • Fixed The map type control was enabled.
  • v.2.0.0 - August 22, 2006 BenWilson August 16, 2006, at 03:33 PM
    • Change Completely reworked the interface. The objective was to reduce the number of options needed to render a valid map.
  • v.1.3.1 - August 15, 2006 BenWilson August 15, 2006, at 02:57 PM
    • Fixed Disabled (:gmap:) lat/lon creation. Editors now have to create a separate (:gmapoint:) for that point, but the info window popup works.
  • v.1.3.0 - August 14, 2006 BenWilson, HelgeLarsen? August 14, 2006, at 03:33 PM
    • Feature Polyline support, introduced by HelgeLarsen?, extended by Ben.
    • Feature Multi-point information windows.
    • Feature Better direction pointing. Now, clicking a direction link opens a new page. Can get directions to and from a point.
    • Feature Can link from a point on the map to an anchor on page, and vice versa.
    • Change Removed PHP centering of the map in favor of Google Map's implementation.
    • Change Zooming is now automatic. Note: I probably should do this for multiple points, rather than one point.
  • v.1.2.1 - August 4, 2006 HelgeLarsen? August 04, 2006, at 02:35 PM
    • Fixed Added support for locales using decimalseparator other than "." as in Denmark.
    • New Feature Added ability to toggle if the center coordinate is added as point.
    • New Feature Added ability to toggle if map center coordinate is calculated.
  • v.1.2.0 - June 3, 2006 BenWilson June 03, 2006, at 04:59 PM Added ZIP code support.
  • v1.1.0 - May 26, 2006 BenWilson May 26, 2006, at 01:49 PM
    • New Feature Added multiple point capability. This feature allows multiple points to be established. The map will center itself based on the range of points given. However, presently does not correct the zoom to include all points. Should be able to take messages on each point.
    • New Feature Added ability to toggle map overview. This is the little box in the lower right corner.
    • New Feature Added ability to toggle map type control.
  • v1.0.3 - May 22, 2006 (pm) BenWilson May 23, 2006, at 10:06 AM
    • New Feature added the ability to determine the height/width of a gmap via the markup.
    • New Feature added the ability to set site-wide defaults for height/width of maps.
  • v1.0.2 - May 22, 2006 (pm) BenWilson May 22, 2006, at 05:33 PM Des did the bright-eyes repair of the features. Control is properly managed.
  • v1.0.1 - May 22, 2006: First Wave BenWilson May 22, 2006, at 02:34 AM
    • Fixed Rendering Issue The Gmap takes up the size of its container. The container was a zero-sized DIV statement. Therefore, the maps were zero sized. I used $HTMLStylesFmt to force a size. I anticipate local system admins can override this at home.
    • Fixed Certificate Confusion Using $HTMLHeaderFmt, I have the code add the proper certification information. So, all the site administrator needs to do is what is in the (updated) documentation.
    • Gmap v.2.0+ Compliance Des made a fine revision to the code, which I've incorporated in work I've done since the first release. His revisions helped bring this recipe into compliance with Google Maps API 2.0
    • Silent Fix Only add the directions block when directions are offered. Before, directions were only offered when a message was given.
    • Silent Fix Only add the message block when the message is offered.
    • Silent Fix If the message or directions are requested, then the window is formed.
    • New Feature Added support for dynamic scaling of controller.
    • New Feature Added the overview map.
    • New Feature Added support for map type (satellite, normal or hybrid).
    • Issue GmapJS remains a problem. I would like to have this put into the page output dynamically rather than asking the site admins to use.
  • v1.0 - May 17, 2006: Initial Release BenWilson May 17, 2006, at 01:08 PM This is a stable release compliant with version GmapAPI 2.0.

Contributors

  • v.2.2.0 - February XX, 2007 BenWilson, (Frank minor effort to fix address cache)
  • v.1.3.0 - August 14, 2006 BenWilson, HelgeLarsen?.
  • v.1.2.1 - August 4, 2006 HelgeLarsen? Minor fixes
  • v.1.2.0 - June 3, 2006 BenWilson Multiple point support.
  • v.1.1.0 - May 26, 2006 BenWilson Multiple point support.
  • v.1.0.3 - May 23, 2006 BenWilson Minor feature release to resolve size for good.
  • v.1.0.2 - May 22, 2006 BenWilson Minor bug fix contribution from Des.
  • v.1.0.1 - May 22, 2006 BenWilson Major bug fix and minor feature release with contribution from Des
  • v1.0 - May 17, 2006 BenWilson Originally written.

Ben Wilson Maintained

User notes +2 -1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.