View Source

h2. Overview
_Since 3.2_

The ace:gMap component, and the subcomponents that tie into it, are designed to provide a comprehensive implementation of the Google Maps Javascript API.

The Google Maps API is a web-based service which requires that the client-browser has access to the Google Maps server via the internet.

{tip}See the ICEfaces Showcase [Live Demo|] of this component, complete with source code.{tip}

h2. Getting Started
<ace:gMap address="Calgary, Alberta" style="height:500px; width:800px;"/>

h2. Attributes
{tip:title=TagLib Documentation}

This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|].
*latitude* and *longitude* represent the location the map should show, either upon rendering, or upon the submission of these values. *zoomLevel* defines the level of zoom that the map shows and *type* is used to set the type of map visible(roadmap, hybrid, satellite and terrain).
The map will automatically move to view the location specified in *address* in the event that the map is rendering, or *locateAddress* is true.
*Options* is a catchall attribute for the oher various options availible to a google map from the Google Maps API. It is done in the style of *optionName:*{_}value_, *optionName:*{_}value_... etc. A list of viable options can be found at [the API documentation|].

h2. Relations to subcomponents

The *ace:gMap* component has a large number of subcomponents, each designed to affect the map in a specific way. All of these components must be nested within an ace:gMap tag in order to function.
* *ace:gMapControl* is a more intuitive approach to modifying the controls that appear on the map. Using this, users can specify which controls render, as well as the location of those controls that do appear.
* *ace:gMapInfoWindow* displays a pop-up window that can display either straight text information, or nested html code. If placed within a gMap, it will render at the locations given by its latitude and longitude attributes. If it is placed inside an ace:gMapMarker, it will bind to that marker and move to whatever location it occupies.
* *ace:gMapLayer* activates a layer on the parent gMap that's designed to provide an alternative visual, such as displaying bike paths, traffic, or third-party KML data.
* *ace:gMapMarker* places a marker upon the map in the desired coordinates to be used for designating points of interest or important locations.&nbsp;
* *ace:gMapOverlay* allows the user to create a shape of their choosing on the map.
* *ace:gMapServices* is an access point to the services portion of the api and will return information about the specified points, such as maximum zoom, or height.&nbsp; Directions are also specified through this subcomponent.
* *ace:gMapAutocomplete* uses the google places api to create a text-box that will auto-complete location entries, centering the map to the location chosen and returning information to specified variables in the backing bean. NOTE: To use this component, you must append 'libraries=places' to the end of your gMap key in the web.xml document.

h2. License Key

The Google Maps API uses an optional license key to identify applications/servers to the gMap service for usage tracking purposes.

By default, the Google Maps API has usage limits in place, as below:
{quote}Web sites and applications using each of the Maps API may at no cost generate:
up to 25,000 map loads per day for each API
up to 2,500 map loads per day that have been modified using the Styled Maps feature{quote}

If an application requires more than that then a commercial agreement can be signed with Google and a specific Google Maps API key is issued for that.
We recommend that users generate their own API keys for use with their production applications, as per the instructions here:

The key is then specified in the web.xml file as follows:
<description>Google Maps API key is required if gMap component is used.
Sign up for an API key from</description>

Note that the ICEfaces Showcase sample application includes a gMap API Key that is keyed to "localhost" for demonstration and testing purposes.

h2. Javascript API

h4. ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the *widgetVar* attribute.

h4. ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

{code}var widget = ice.ace.instance('frm:componentId);{code}

{tip}The _ice.ace.instance_ function requires the _full_ client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use {{prependId="false"}} in the enclosing form (e.g. _<h:form prependId="false">_).{tip}

{info}This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

h2. Required

In order to function properly, ace:gMap must be able to access a Google Maps v3 API key. This can be achieved by setting a parameter 'org.icefaces.ace.gmapKey' to your key in your project's web.xml. A google maps v3 API key can be obtained for free [here|].

h2. Version

By default, ace:gmap will use the latest Google Maps version available. If an earlier version is preferred for a certain application, then the {{org.icefaces.ace.gmapVersion}} context parameter must be specified in web.xml with the desired version number as the value, as in this example:


In this case, the 3.21 version will be used, whose control styles are clearly different than in newer versions. Only versions that are still supported by Google can be used in this way.

h2. CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<div class="ice-ace-gmap [user defined classes]" style="[user defined styles]">
<!-- Nodes added by Google Maps... -->