GMaps4JSF, a JavaServer Faces (JSF) mashup library, integrates Google Maps with JSF. Using GMaps4JSF, you can construct complex street view panoramas and maps with just a few JSF tags. You can also easily attach different components to the map. This article explains how to configure GMaps4JSF inside JSF 2.0 applications, and includes a brief introduction to JSF 2.0 Ajax. Using the article, learn how you can create a simple mashup application that uses both GMaps4JSF and JSF 2.0 Asynchronous JavaScript and XML (Ajax).


Hazem Saleh, Staff Software Engineer, IBM  

Photo of Hazem SalehHazem Saleh has five years of experience in JEE and open source technologies. He is committed to Apache MyFaces and is the initiator of many components in the MyFaces projects such as Tomahawk CAPTCHA, Commons ExportActionListener, Media, PasswordStrength, and others. He is the founder of GMaps4JSF (an integration project that integrates both Google Maps with Java ServerFaces), and is the author of "The Definitive Guide to Apache MyFaces and Facelets (Apress)." He is now working for IBM Egypt as a staff software engineer, where he is recognized as a subject matter expert in Web 2.0 technologies.

developerWorks Contributing author

25 August 2009

Also available in Chinese Japanese


GMaps4JSF aims to integrate Google maps with JavaServer Faces (JSF) and lets JSF developers construct complex street view panoramas and maps with just a few JSF tags. You can also easily attach different components (markers, information texts, controls, ground overlays, polygons, polylines) to the map. GMaps4JSF also allows attaching different server-side and client-side events to components without writing JavaScript code to bind the event with the component. You only need to write JavaScript code if you want to implement the components' client-side event handlers.

Ajax is a primary technology in any modern Web application. Although Ajax was not introducted in the earlier versions of JavaServer Faces, it was provided by many JSF component libraries like Apache MyFaces Trinidad, JBoss RichFaces, ICEFaces, and others. Now the good news is that Ajax is supported natively in JSF 2.0 implementations.

In this article, I explain how to configure GMaps4JSF inside your JSF 2.0 application and give a brief introduction to JSF 2.0 Ajax. Finally, I'll illustrate a simple mashup application that uses both GMaps4JSF and JSF 2.0 Ajax.

Configuring GMaps4JSF with your JSF 2.0 application

First, let's configure GMaps4JSF with your JSF 2.0 application. To do this:

Sign up for the Google Maps API (see Resources). You will need to accept the usage agreement and register the site that you are using for your application. In return, Google provides a key specific for your application.

Figure 1. Sign up for the Google Maps API
Screen shot of the agreement screen for Google Maps API

To use the Google Maps API you must include the Google Maps API's script in your page. Listing 1 shows the Google Maps API's script that must be included in your <h:head> tag. You can find full details of how to use this code in the Google Maps API documentation (see Resources).

Listing 1. Header codes to include the Google Maps API

In the code in Listing 1 you will need to replace the phrase "gen_website_key" with they key provided to you during your registration. Figure 2 shows an example of this key on the Google Maps Web site and how it fits into your code.

Figure 2. Put in your page <h:head> tag the Google Maps APIs script include
The code sample from Listing 1 is shown with a partial screen shot of the Google Maps API page. gen_website_key in the code is circled with red and an arrow points to the lengthy key string on the Google Maps web page.

Next you will need the JAR file for GMaps4JSF. Download the latest version from the project Web site (see Resources). Figure 3 shows the project page with the downloads on the right.

Figure 3. Download the latest library snapshot jar
Screen shot of the GMaps4JSF home page with the download files in the right-hand menu circled with red.

Place the downloaded JAR file in the WEB-INF/lib directory of your JSF 2.0 Web application.

Finally, add the library declaration shown in Listing 2 to your XHTML page in order to use GMaps4JSF components.

Listing 2. Library declaration for GMaps4JSF components
<html xmlns=""

Using JSF 2.0 Ajax

Ajax is now a part of most of modern Web 2.0 applications. Writing "Ajaxified" applications from scratch can be a headache. On the client side, you must write a JavaScript client to send the Ajax requests and to receive the Ajax responses. On the server side, the application must prepare a response that can be understood by the client. In addition to all of these complexities, the JavaScript client code should be cross-browser compatible. JSF 2.0 Ajax does all of this for you.

In JSF 2.0, there are two ways of adding Ajax support to the JSF 2.0 applications. You can use the JavaScript library provided by the framework or the new <f:ajax> tag to declare Ajax support for the JSF components.

The <f:ajax> tag enables the creation of Ajax requests that are attached to the JSF components' actions. For example, if the <f:ajax> tag is put inside an action source component such as <h:commandButton>, it allows sending Ajax requests upon the "onclick" action of this component. If the tag is put inside a value holder component like <h:selectOneListbox>, it allows sending the Ajax requests upon the "onchange" action of the component.

Listing 3 shows how easy it is to use JSF 2.0 Ajax. In this example, the <f:ajax> tag is put inside the <h:inputText> component. So when the user enters a value in the txtName input text and tabs out, the txtEnteredNameoutputText will be updated with the entered value.

Listing 3. The JSF 2.0 <f:ajax> tag usage example
<h:panelGrid columns="2">
    <h:outputText value="Enter your name:"/>
    <h:inputText id="txtName" value="#{}">
        <f:ajax render="txtEnteredName"/>
    <h:outputText value="You entered: "/>
    <h:outputText id="txtEnteredName" value="#{}"/>

The Countries application

Now, let's move to the Countries application, which uses both GMaps4JSF with JSF 2.0 Ajax. In this application, you have a master dataTable and a detailed map. Each row of the dataTable represents a country, and when the user clicks on a row the country location is displayed in the detailed map. Figure 4 shows a screenshot of the Countries application in action.

Figure 4. The Countries application screenshot
A screenshot of the Countries application shows a list of various countries in the top of the window with a google country map below. There is a marker in Egypt with a description window giving details about the country.

Listing 4 shows a partial listing of the mashups.xhtml code, the Countries application XHTML page. I put the <f:param> tags inside the <f:ajax> tag so I can send the parameters when the table row "View Country Location" commandLink is clicked. In the render attribute of the <f:ajax> tag, the ID of the panel group containing the map component is specified "mapGroup". When the response comes from the server, the map will be updated with the new information #{param.selectedCountry}, #{param.selectedCapital}, and #{param.continent}.

Listing 4. (mashups.xhtml) the Countries application XHTML page
<!-- some code here -->
<h:dataTable value="#{}" var="row">
   <!-- some code here -->
    <f:facet name="header">
      <h:outputText value="Action"/>
	<h:commandLink id="cmdShow" value="View Country Location"> 
       <f:ajax render="mapGroup"> 
          <f:param name="selectedCapital" value="#{}"/> 
          <f:param name="continent" value="#{row.continent}"/> 
          <f:param name="selectedCountry" value="#{}"/> 
<!-- some code here -->
 <h:panelGroup id="mapGroup"> 
    <m:map id="map" width="460px" height="460px" type="G_NORMAL_MAP" 
      rendered="#{param.selectedCountry ne null}" renderOnWindowLoad="false" zoom="4"> 
    <m:marker id="marker"/> 
    <m:htmlInformationWindow id="window" 
       htmlText="Country: #{param.selectedCapital} <br/> Continent: #{param.continent}"/> 
    <!-- some code here --> 

Listing 5 shows the Countries application sample managed bean. Note that you can get this managed bean data from a database or a Web service, but for the case of my demonstration it just holds static information about the different countries.

Listing 5. Countries application sample managed bean
public class CountryTableModel {
	private static List<Country> data = new ArrayList<Country>();
	static {
		data.add(new Country("Egypt", 
		                     "Cairo, Egypt", 
		data.add(new Country("Germany", 
		                     "Berlin, Germany", 
		data.add(new Country("Austria", 
		                     "Vienna, Austria", 
		data.add(new Country("US" , 
		                     "Washington, USA", 
		                     "North America"));
		data.add(new Country("China" , 
		                     "Beijing, China", 
		data.add(new Country("Brazil" , 
		                     "Brazilia, Brazil", 
		                     "South America"));		

	public List<Country> getData() {
		return data;

	public void setData(List<Country> data) { = data;


In this article, you saw how JSF 2.0 simplifies building "Ajaxified" applications. You also saw how it is easy to construct Google maps, and attach different markers, notes, and controls to them using GMaps4JSF. I explained how simple it is to use GMaps4JSF in JSF 2.0 applications, and now you, as a JSF 2.0 developer, can easily build Web 2.0 mashups inside JSF 2.0 applications without having to write JavaScript code.


Source codemashups2-Eclipse-sourcecode.zip7674KB



Get products and technologies


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Web development on developerWorks

Zone=Web development, Java technology
ArticleTitle=GMaps4JSF in the JSF 2.0 Ajax world