cf_googleMap Documentation

Version: 1.4
Build Date: 6/10/2008
Created By: John Blayter
Project Page | Blog | RIA Forge | Forums | Known Issues | Subversion Access | Download
License: Apache License, Version 2
History
1.4 (1) Added the showTraffic attribute to the cf_googleMap tag.
(2) Added the showLocalSearch attribute to the cf_googleMap tag.
(3) Added a language attribute to the cf_googleMap tag.
(4) Added the enableZoomScroll to the cf_googleMap tag and defaulted it to true so a use can use their scroll wheel to zoom in and out
(5) Added the enableGE to the cf_googleMap tag and defaulted it to false to enable the Google Earth view of the map.
1.3.1 (1) Added the option to view a overview map.
(2) Added logic to not add the point to the map if the latitude or longitude are numeric
(3) Fixed zooming issue where controls are not active until the point is clicked or the map is dragged
1.3 (1) Changed the logic for the mainpoint attribute so it can be overwritten when a false value is passed.
(2) Added documentation for to the mainpoint and how it defaults to true when there is 1 point on a map
(3) Removed the default 1px blue border around the DIV container for the map and replaced it with a style attribute for the googlemap tag.
(4) Added the show attribute to the cf_googleMapPoint tag
(5) Added the GM_clearMap() JavaScript function
(6) Changed the max characters for the driving directions from 40 to 255
(7) Added example for using the geo.cfc Geocode
(8) Renamed the Geocode function to GeocodeUS
(9) Added a new Geocode function based off of code provided by Jeff Gladnick. This should provide a much more accurate geocoding including international addresses.
(10) Added callJavaScript attribute to the cf_googleMapPoing tag
1.2 Added fit points to map functionality
1.1 Changed tag to work with version 2 of the API and draggable points
1.0 Initial Release

Table of Contents

  1. Overview
  2. Tag Attributes
  3. JavaScript API
  4. Examples
  5. Resources
  6. Troubleshooting
  7. To do...

Overview

CF_GoogleMap is a ColdFusion custom tag that allows for the integration of GoogleMaps into your website. There are 4 tags that you can use in combination to create various maps.

Tag Attributes

CF_GoogleMap

Attribute Req/Opt Default Description
Key Required   This is your key that you get when you sign up for the Google Maps API. You can sign up for this Key at http://www.google.com/apis/maps/signup.html.
Width Optional 600 Width of the map.
Height Optional 450 Height of the map.
DefaultCSS Optional True A True/False flag saying if you would like the tag to output it's default CSS for the popup window. The map uses a class name of .GM_InfoWindow so if you want to customize the style you can set this value to False and create this class name in your existing CSS file.
ControlType Optional Large Large/Small are the 2 types of possible controls that allow the user to zoom in/out.
showTraffic Optional false A True/False flag saying if you would like to show the traffic on the initial load of the map.
showLocalSearch Optional false A True/False flag saying if you would like to show the local search box on the map.
language Optional en A 2 character ISO language code. A list of supported language can be found here.
enableZoomScroll Optional true A True/False flag enabeling the scroll wheel to be used for zooming in and out of the map.
enableGE Optional false A True/False flag saying if you would like to show the option for the Google Earth view. Please note that a plug-in is used for this.
MapType Optional Map MAP,HYBRID,SATELLITE are the 3 types of possible default maps.
Level Optional 12 Zoom level you initially want the map zoomed to
CenterLon Optional   This is the default center longitude for the when the map loads. If there is no value for this and there is just 1 point the longitude of that point will be used. If there is no value for this and there is a point with the MainPoint attribute it will use the longitude from that point. If there is not a value after all this it will default to a Longitude point roughly in the center of the United States at -98.7451171875.
CenterLat Optional   This is the default center latitude for the when the map loads. If there is no value for this and there is just 1 point the latitude of that point will be used. If there is no value for this and there is a point with the MainPoint attribute it will use the latitude from that point. If there is not a value after all this it will default to a latitude point roughly in the center of the United States at 40.1452892956766.
BrowserNotCompatible Optional   This is the error that the user sees when their browser is not compatible with Google Maps. The default error message is "We're sorry but your browser is not compatible with Google Maps".
dragStart Optional   JavaScript that is executed when a point is started to be dragged. Both lon and lat JavaScript variables are present already for you to use.
dragEnd Optional   JavaScript that is executed when a point has stopped being dragged. Both lon and lat JavaScript variables are present already for you to use.
fitPointsToMap Optional false A True/False flag saying if you would like all of the points to fit on the map when it is initially loaded. The map will automatically set the correct zoom and center location based on all the points passed into the tag.
style Optional   Any inline CSS that you would like applied to the DIV container that the map is in. Please note that the width and the height attributes are already populated from the width and height attributes.
overviewMap Optional false A True/False flag saying if you would like the overview map on the page
overviewMapWidth Optional 200 The width in pixels of the overview map
overviewMapHeight Optional 200 The height in pixels of the overview map
proxyURL Optional   A relative URL to the proxy.cfm file. Since Google Maps API does not support calling the main JavaScript in an SSL environment. The main JavaScript must be called through a proxy to go and get the file and return it in an unsecure manner. There is also a bit of caching built into the proxy.cfm. It stores the returned JavaScript within the application.cfGoogleMap.JSCache variable. (If your network requires the use of proxies you can set these within the proxy.cfm file.

CF_GoogleMapIcon

Attribute Req/Opt Default Description
IconURL Required   This is your url to your custom icon relative to the page that it is loading on. Your icon needs to be a PNG. You do not need a full url like http://mydomain.com/logo.png you can just use a path like /images/logo.png
IconName Required   This is the name of the icon. You will refer to this name later when using it in a point (make sure that the point name does not contain a dash "-")
Width Required   Width of the icon.
Height Required   Height of the icon.
IconAnchor Optional 1/2 of the width attribute,1/2 of the height attribute The pixel coordinate relative to the top left corner of the icon image at which we should anchor this icon to the map. For example if you have an icon that is 20 x 20 and you wanted to anchor it from the center bottom your value that you pass would be "10,20"
InfoWindowAnchor Optional 1/2 of the width attribute,2 The pixel coordinate relative to the top left corner of the icon image at which we should anchor the info window to this icon. For example if you have an icon that is 20 x 20 and you wanted to anchor it from the center top your value that you pass would be "10,1"

CF_GoogleMapLine

Attribute Req/Opt Default Description
Color Optional #ff0000 Hex color of the line
Size Optional 4 This is the thickness of the line
Opacity Optional 0.5 A value between 0 and 1 determining the opacity of the line being drawn.

CF_GoogleMapPoint

Attribute Req/Opt Default Description
Lat Required   Latitude of the point.
Lon Required   Longitude of the point.
Title Required   Info Window: Title of the window.
(If the CF_GoogleMapPoint is inside a CF_GoogleMapLine this attribure is not required.)
Address Required   Info Window: Address of the location.
(If the CF_GoogleMapPoint is inside a CF_GoogleMapLine this attribure is not required.)
IconName Optional   The name of the custom icon defined in the CF_GoogleMapIcon tag
PointName Optional markerN The name of the point. You can later use this name by calling the JavaScript GM_viewProperty function. (make sure that the point name does not contain a dash "-")
MainPoint Optional   If a CF_GoogleMapPoint has the MainPoint attribute the map will use that point as the main point for the map. When the map loads it will center on this point and automatically open the information window. This is useful when you have a main destination on the map and you want to relate other points to this. If you only have 1 point it defaults the mainpoint attribute to TRUE. You can override this by passing the mainpoint attribute with a FALSE value.
Center Optional   If a CF_GoogleMapPoint has the center attribute the map will use that point as the center point for the map when initially loaded.
Draggable Optional false A true/false flag determining if the point is draggable.
Show Optional true A true/false flag determining if the point shows when the page loads.
callJavaScript Optional   A string of input parameters to send to the onGmapBubbleClick() javascript function. Ie "'bill', 'smith', 45, 2006". Please note that the tag does not output the onGmapBubbleClick() function rather than just call it. You will need to create this function and place your custom logic in there.

CF_GoogleMapShow

Because not all of us program with 100% XHTML compliant code there is a work around to get the map to show in your HTML code. What you need to do is place the CF_GoogleMapShow right before your closing body tag and it will take the JavaScript content to render the map and execute it at the bottom of the page. You still can have the map located anywhere in your HTML; its just the execution code needs to be at the end.

JavaScript API

GM_viewProperty

GM_createMarker

GM_clearMap

GM_clearMap() removes all points on the map. It takes no arguments.

Troubleshooting

My map works in FireFox but throws an error in IE

You need to make sure that you have the

<cf_googlemapshow/>
tag right before your closing body tag.

What happened to my application scope?

In the download there is an Application.cfm that sets the application.googleMapKey. This is just in there for the examples you can delete this and add the application.googleMapKey to your application.cfm/cfc

Why dosnet the geocode function return a lat/lon for my address in the UK, Japan and China?

The Maps API geocoder provides detailed geocoding for Andorra, Australia, Canada, France, Germany, Italy, Japan (but only in Japanese), Netherlands, New Zealand, Spain, and United States of America. For countries other than the UK and China it provides geocoding for country names and city names (e.g. "Nairobi, Kenya"). (source)

To do...

Here is a list of various items I would still like to add to this tag set. I am not sure if or when they will be added. It is just a public list of ideas