The Google Maps Plugin

Need help installing Zap Calendar? Click here for a tutorial on installing Zap Calendar, or find out how to add additional functionality to your Zap Calendar site with the dozens of add-ons available for Zap Calendar.

Plugin Name: googlemaps

Availability:

googlemaps calendar Purpose: To display event locations on a map. This plugin can display a map location for a single event (event display) or for a group of events (monthly, weekly, upcoming and static list of events display). Users can also optionally search for events near their location. Features of this plugin include:

Bulk geocoding of events
Search events near your location
Driving directions support
Color coded icons based on category color
Custom styles for map display
Display map for events that occur on a particular day, week or month
Compatible with category chooser, show map locations by category
Ability to move map pin manually to fine-tune location
Google Maps v3 API support
My Location: utilize browser location feature in HTML 5
Category icons: Maps can now display either category icons or the standard pin icons

Configuration:

Version 3.1 and above of the Google Maps plugin uses the Google Maps version 3 API. Plugin versions earlier than 3.1 use an API no longer supported by Google will no longer work.

If you have not done so yet, sign up for a Google account and get a Google Maps API key from this URL (note: the URL has changed) : http://code.google.com/apis/console . From the services menu, enable the "Google Maps API v3" option. You will need the Google API key to insert into the Google Maps plugin. This key can be found the "API Access" menu option. More information about obtaining a Google API key can be found here:

https://developers.google.com/maps/documentation/javascript/tutorial#api_key

Setup

Your key can be found in the "API Access" menu option from Google's API console. To use this key on multiple sites, enter each site where the plugin will be installed in the "Edit allowed referers". Once you obtain the key, go to Joomla Plugin Manager on your site and edit the Google Maps plugin (under the zapcalendar folder). Enter your API code here.

Completing the Installation (Zap Calendar Version 3.x Only)

After enabling the plugin and entering the API key, you will need to go to the Zap Calendar control panel in the back-end to complete the installation. From the panel, click the "Complete Install" (you may not see this option when upgrading from a previous version).

View Settings

The map display is controlled from a Zap Calendar view's plugin settings. Use the plugin settings to enable the plugin. When viewing a single event, no map is displayed if the event does not have a location specified. The pin color of the event is based on the event's category. If an event belongs to more than one category, the first category's color will be used.

The plugin automatically converts locations to latitude/longitude coordinates. When creating a new event, the plugin settings allow for an alternate location to be used for lat/long purposes. For example, the location McDonald's" by itself will not be locatable due do the many possible locations; however, an alternate address can be entered to determine lat/long coordinates while still keeping the location description as "McDonald's". If the geocoded position is not correct, the pin on the map can be dragged to the correct position.

Beginning with Zap Calendar 4.0.15, you can use custom styles for your Google Map. This allows you to customize how your Google Map will appear in Zap Calendar. One way to do this is to visit the site www.snazzymaps.com , select a map style, copy the JavaScript style array code and paste it into the map style field. From the wide selection at this web site, you can choose from vibrant color to monochrome map styles. You can also try out the Google Maps Style Wizard on the web to create your own custom style.

Proximity searching is also enabled in the view's plugin settings. Set the units (kilometers or miles) and up to three distances to search. For example, if units are set to kilometers and the distances 50, 100, and 200 are entered, this will allow users to search for events up to 50 km, 100 km and 200 km within their location, respectively. Distances are based on a straight line calculation and not driving distance.

Bulk Geocoding

Geocoding is the term used to convert a street address to a latitude/longitude coordinate. Bulk geocoding can occur when importing many events from an icalendar or CSV import, which may have a street address but will not have a latitude/longitude location. It can also occur when installing the Google Maps plugin into an existing calendar that already contains events.

In order to perform bulk geocoding, the Google Maps API geocoding limit must be raised. By default, one geocoding per second is the maximum. This limit can be raised to increase the number of geocodings per second. A rate of 10 per second is the recommended value for this setting with Zap Calendar. This can be updated under the Quotas section in the Google API console. This rate can be modified for both v2 and v3 API's.

Bulk geocoding is done automatically in the back-ground when a user browses the monthly or weekly calendar. The map will populate automatically when new locations are found and geocoded. It may take a few map refreshes to see all the map locations in a month view.

Google allows up to 2,500 geocodings and 25,000 map views per day per website without charge. Higher maximums will require contacting Google for a license. If you have installed a Google Maps API key, you can monitor your site's quotas at the API console.

Known issues:

Only one map can be displayed per page. The map will not be displayed if several Zap Calendar modules are being used on the same page with the Google Maps plugin enabled. Disable the Google Maps plugins from these modules/views so that only one view on the page has it enabled.

Events with the same location will have overlapping markers, however, only one of the markers will be clickable.

The plugin automatically converts locations to latitude/longitude coordinates and caches them as it finds them. These locations may not appear on the map the first time they are found, but will be displayed in subsequent map displays. When importing events, it may be useful to page through the monthly map to allow the plugin to cache these new locations.

Occasionally, the locations are not automatically geocoded for various reasons. You can display these "missing" locations from the Tools menu in Zap Calendar 4 or the Admin Tools area in Zap Calendar 3 for manual geocoding.