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.
In order to make use of MapFace, you must use facelets in your 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>
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 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:
Example:
<rd:map mapId="map_canvas" width="100%" height="100%" key="abcdefg"/>
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:
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>
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:
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<br>Huizingen" for="RealDolmen_Huizingen" /> </rd:marker> </rd:map>
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:
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<br>Huizingen" for="RealDolmen_Huizingen" /> </rd:marker> ... two hundred more markers <rd:clusterer maxVisibleMarkers="100" /> </rd:map>
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<br>Huizingen" for="RealDolmen_Huizingen" iconLink="icons/someIcon.png" /> </rd:marker> </rd:map>
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:
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<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>
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>