GMap3 Wicket Component

This component (isis-wicket-gmap3) allows an entity or collection of entities to be rendered within a map (using google’s gmap3 API).


The module’s functionality can be explored by running the quickstart with example usage using the

Note that the isis.viewer.wicket.gmap3.apiKey must be set to a valid value; this is most easily done using a system property.

A home page is displayed when the app is run:

010 install fixtures

Parented collection as gmap

The todo item’s collection contains a list of Locatable entities (also todo items); this is indicated through a button to switch the view:

020 gmap button available on parented collection

Clicking the button shows the same entities on a gmap3:

030 view collection in gmap3 next update location

Update location using service

This module previously provided a "LocationLookupService". This has been removed, since the underlying gmap3 geocoding service requires an .apiKey. A similar GeocodingService, providing a superset of functionality, is available in commchannel module (though this may move into its own library in the future, see #57).

Standalone location as gmap

Invoking an action that returns a list of Locatable entities also results in the button to view in a gmap3:

070 gmap button available on standalone collection

... which then renders the items in a map. Note the tooltips:

080 view collection in gmap3

Click through

Clicking on a map marker drills down to the entity:

090 click through to entity

API & Usage

Rendering objects on a map

Make your entity implement org.isisaddons.wicket.gmap3.applib.Locatable, such that it provides a Location property of type org.isisaddons.wicket.gmap3.applib.Location.

This property will need to be annotated as @javax.jdo.annotations.Persistent.

For example:

import org.isisaddons.wicket.gmap3.cpt.applib.Locatable;
import org.isisaddons.wicket.gmap3.cpt.applib.Location;

public class ToDoItem implements Locatable {
    private Location location;

    @MemberOrder(name="Detail", sequence = "10")
    public Location getLocation() {
        return location;
    public void setLocation(Location location) {
        this.location = location;

You should then find that any collections of entities that have Locatable properties (either returned from an action, or as a parented collection) will be rendered in a map.


Sometimes the domain object that implements Locatable will be a supporting object such as an Address, belonging to a Customer, say. When the location marker is clicked in the map, we would rather that the UI opens up the Customer rather than the associated Address (in other words, saving a click).

This requirement is supported by providing an implementation of the LocationDereferencingService:

public interface LocationDereferencingService {
        Object dereference(final Object locatable);

for example, one might have:

public class LocationDereferencingServiceForAddress implements LocationDereferencingService {
        public Object dereference(final Object locatable) {
                if (!(locatable instanceof Address)) {
                        return null;
                final Address address = (Address) locatable;
                return address.getCustomer();

Note that there can be multiple implementations of this service; the component will check all that are available. The order in which they are checked depends upon the @DomainServiceLayout(menuOrder=…​) attribute.

How to configure/use


Add the component to your project’s dom module’s pom.xml:


Check for later releases by searching Maven Central Repo.

For instructions on how to use the latest -SNAPSHOT, see the contributors guide.


In the AppManifest, update its getModules() method, eg:

public List<Class<?>> getModules() {
    return Arrays.asList(

Configuration Properties

gmap3 API Key

In order to use the component an API key is required. See the google documentation for instructions as to how to do this; a free key (with quite generous daily limits) can be used.

Configure the key in WEB-INF/ (or WEB-INF/


The commchannel module also requires the same configuration, though under a different configuration property.

Known issues

None known at this time.


Maven can report modules dependencies using:

mvn dependency:list -o -pl modules/wkt/gmap3/impl -D excludeTransitive=true

which, excluding Apache Isis itself, returns these compile/runtime dependencies:


For further details on 3rd-party dependencies, see:

In addition to Apache Isis, this component depends on: