Introduction

MapFace is a product derived from a business need within RealDolmen. Within the company grew the demand for an application in which the employees, customers, RealDolmen quarters, ... would be placed on a map. A small project was set up. Two developers searched for libraries that already had implemented the requirements. None seemed sufficient enough, so they started out creating the application from scratch, making use of the Google Maps API. Eventually, a reusable component of a part of the application was demanded. This is where the story of Mapface starts. But what is MapFace?

MapFace is a custom component for facelets. It integrates Google Maps in a JSF page that makes use of facelets. There are many possibilities provided by the map. For instance, you can add multiple markers which can be clustered if desired. Besides that there's a possibility to search for markers on the map and to plan routes between two markers.

This document will describe how to use MapFace in your facelet application and where to find the source code and how to adjust it.

Using MapFace

In order to make use of MapFace, you must use facelets in your project!

Setup

Include in Maven project

To include the MapFace component in your Maven project, just add the following dependency.

<dependency>
    <groupId>com.realdolmen.sf</groupId>
    <artifactId>mapface</artifactId>
    <version>1.0</version>
</dependency>

Include in non-Maven project

Download the library from here into the lib-folder of your project.

In the page where you want to make use of the mapface, you must add an extra xml namespace. This namespace is xmlns:rd="http://www.realdolmen.com/mapface". So, it might look like this:

<ui:composition
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:rich="http://richfaces.org/rich"
    xmlns:rd="http://www.realdolmen.com/mapface">

Showing a map

Showing a single map is straight forward. The tag that is used is <rd:map>. A few attributes need to be filled in.

For a full overview of all tags and attributes, please check the api-document.

Required attributes:

  • mapId: the id of the map
  • width: the width you want the map to have. This can be in pixels or in percent.
  • height: the height you want your map to have. This can be in pixels or in percent.
  • key: This is the Google Maps key that you can acquire at http://code.google.com/intl/nl/apis/maps/signup.html

Example:

<rd:map mapId="map_canvas" width="100%" height="100%" key="abcdefg"/>

Adding markers

A marker is a point on the map with certain coordinates. It has an icon and an info window. To add a marker use the tag <rd:marker>. The marker tag has a couple of required attributes. Two of them are address and city. These must be filled in so the locations can be looked up via the Google Maps Webservice. Besides address and city there are two other attributes to locate the position. These are longitude and latitude. If those attributes are filled in, the Google Maps Webservice won't be called.

Required attributes:

  • address: street and house number of the position
  • city: postal code and city name of the position. The country can be entered here as well.
  • id: the unique id of the marker.
  • name: name of this marker, (for example the name of a building) used to display in the search results and in the infowindow of the clusterer

Example:

<rd:map mapId="map_canvas" width="100%" height="100%" key="abcd">
    <rd:marker id="marker1" name="RealDolmen Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen" />
</rd:map>

Adding an info window to a marker

An info window is the cartoon-like balloon that appears if you click on a marker. In that info window you can add all the information you want. The tag <rd:infoWindow> is a child of marker.

Required attributes:

  • text: the value you want inside the infoWindow.
  • for: the id of the marker for which the infoWindow is created.

Example:

<rd:map mapId="map_canvas" width="100%" height="100%">
    <rd:marker id="RealDolmen_Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen">
        <rd:infoWindow text="Realdolmen HeadQuarters&lt;br&gt;Huizingen" for="RealDolmen_Huizingen" />
    </rd:marker>
</rd:map>

Clustering

What do you do when there are so many markers on the map that it becomes complete chaos? You cluster it!

Clustering means that markers are grouped into a single clustering marker. Which markers are added to a cluster is calculated, so you don't have to add them manual. All you have to do is add the cluster tag <rd:clusterer>.

Non-required attributes:

  • gridSize: The size of the grid for which a cluster marker will be created. Standard value is 16. (For example, if you specify 5, there can be 5 markers from east to west across the map)
  • minMarkersPerCluster: the minimum amount of markers in a cluster. Standard value is 3.
  • maxVisibleMarkers: The maximum amount of markers that are visible on the map. Standard value is 120.

Example:

<rd:map mapId="map_canvas" width="100%" height="100%">
    <rd:marker id="RealDolmen_Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen">
        <rd:infoWindow text="Realdolmen HeadQuarters&lt;br&gt;Huizingen" for="RealDolmen_Huizingen" />
	</rd:marker>

		... two hundred more markers

    <rd:clusterer maxVisibleMarkers="100" />
</rd:map>

Changing the marker icon

To make the marker icon more visible and divers, it is possible to the change the icon. An icon can be changed by the iconLink attribute in the <rd:marker> tag.

Example:

<rd:map mapId="map_canvas" width="100%" height="100%">
    <rd:marker id="RealDolmen_Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen">
        <rd:infoWindow text="Realdolmen HeadQuarters&lt;br&gt;Huizingen" for="RealDolmen_Huizingen" iconLink="icons/someIcon.png" />
    </rd:marker>
</rd:map>

Changing the cluster icon

To make the cluster icon more visible and divers, it is possible to the change the icon. The tag <rd:clusterIcon> has a wide variety of required attributes. The tag is a child of <rd:clusterer> and should be added within that tag.

Required attributes:

  • iconLink: The url to the icons' image.
  • shadowLink: The url to an image of the icons' shadow
  • iconWidth: The width of the icons' image.
  • iconHeight: the height of the icon's image.
  • shadowWidth: the width of the shadows' image.
  • shadowHeight: the height of the shadows' image.
  • iconAnchorX: The x-value of the pixel coordinate relative to the top left corner of the icon image at which this icon is anchored to the map.
  • iconAnchorY: The y-value of the pixel coordinate relative to the top left corner of the icon image at which this icon is anchored to the map.
  • infoWindowAnchorX: The x-value of the pixel coordinate relative to the top left corner of the icon image at which the info window is anchored to this icon.
  • infoWindowAnchorY: The y-value of the pixel coordinate relative to the top left corner of the icon image at which the info window is anchored to this icon.
  • infoShadowAnchorX: The x-value of the pixel coordinate relative to the top left corner of the icon image at which the info window's shadow is anchored to this icon.
  • infoShadowAnchorY: The y-value of the pixel coordinate relative to the top left corner of the icon image at which the info window's shadow is anchored to this icon.

Example:

<rd:map mapId="map_canvas" width="100%" height="100%"> 
    <rd:marker id="RealDolmen_Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen">
        <rd:infoWindow text="Realdolmen HeadQuarters&lt;br&gt;Huizingen" for="RealDolmen_Huizingen" />
	</rd:marker>

	... two hundred more markers

    <rd:clusterer maxVisibleMarkers="100">
        <rd:clusterIcon iconLink="img/cluster.png"
            shadowLink="img/shadow_cluster.png" 
            iconWidth="28"
            iconHeight="46" shadowWidth="51"
            shadowHeight="46" 
            iconAnchorX="12"
            iconAnchorY="30" infoWindowAnchorX="12" 
            infoWindowAnchorY="3"
            infoShadowAnchorX="24" infoShadowAnchorY="34" />
	</rd:clusterer>
</rd:map>

Searching and route planning

To search within the markers or plan routes between two points, you just have to set a variable in the <rd:map> tag to true. Enable searching with search="true" enable the route planner with showDirections="true".

Next step is to add the panels you desire. Each of the search and route planning functions has their own panel. The search panel can be added with the tag <rd:searchPanel>, the route planning panel with the tag <rd:direction el>.

Attention! These panels do not have any lay-out. You should use CSS to create the lay-out of the panels as you want.

If you want to search for a marker, make sure your markers have the attribute searchValue filled in. SearchValue is the value in which the search function will look for the given search string.

The following example will create the two panels and the map. The panels will be on the left and the map on the right. The search panel will have a yellow background.

Example

<div style="width:100%; height: 100%"> 
    <div style="width:18%; height: 100%; float: left;">
	    <rd:searchPanel id="searchPanel" style="background-color: yellow;border: 2px;" />
	    <rd:directionsPanel id="directionsPanel" />
	</div>
    <div style="width: 80%; height: 100%; float: right">
        <rd:map mapId="map_canvas" width="100%" height="100%" showDirections="true" search="true" autoCenter="true" key="abcdefg">
            <rd:marker id="RealDolmen_Huizingen" address="A. Vaucampslaan 42" city="1654 Huizingen">
                <rd:infoWindow text="Realdolmen HeadQuarters<br>Huizingen" for="RealDolmen_Huizingen" />
			</rd:marker>

			... two hundred more markers

            <rd:clusterer maxVisibleMarkers="100">
                <rd:clusterIcon iconLink="img/cluster.png"
                    shadowLink="img/shadow_cluster.png" 
                    iconWidth="28"
                    iconHeight="46" shadowWidth="51"
                    shadowHeight="46"
                    iconAnchorX="12"
                    iconAnchorY="30" infoWindowAnchorX="12" 
                    infoWindowAnchorY="3"
                    infoShadowAnchorX="24" infoShadowAnchorY="34" />
		    </rd:clusterer>	
		</rd:map>
	</div>
</div>