Put Google Maps In Your ZK Application

{{Template:Smalltalk_Author|
|author=Henri Chen, Principal Engineer, Potix Corporation
|date=October 16, 2006
|version=Applicable to ZK 10/16 Freshly and later.

::Google Maps Version 2
}}


=Purpose=

A maps component is quite useful for those applications that need to locate an address or position. Besides ping point a specific position on earth, some application also use such component to show the vehicle route and other things. The ZK team has integrated the Google Maps into a '''gmaps''' ZK component, so ZK application developers can now use this originally a javascript component with pure Java code. This article is mainly on how to use this new component and what function has been integrated.


=Installation=

To use this '''gmaps''' component, you have to first copy the new '''gmapsz.jar''' under zkforge folder to ${TOMCAT}/shared/lib and reboot or copy it to WEB-INF/lib of your web application and deploy. For detail ZK installation, please refer to our [http://www.zkoss.org/doc/ZK-quickstart.pdf Quick Start Guide].


=The "Hello, World" of Google Maps=

If you have checked the Google Maps API document, you will probably have seen this [http://www.google.com/apis/maps/documentation/#The_Hello_World_of_Google_Maps example]. It is the "Hello, World" of Google Maps. Writing about twenty lines of HTML and javascript codes, you have a Google Maps embedded in your web page.

<source lang="xml" >
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Maps JavaScript API Example</title>
    <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=abcdefg"
            type="text/javascript"></script>
    <script type="text/javascript">
    //<![CDATA[

    function load() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(document.getElementById("map"));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
      }
    }

    //]]>
    </script>
  </head>
  <body onload="load()" onunload="GUnload()">
    <div id="map" style="width: 500px; height: 300px"></div>
  </body>
</html>
</source>

[[Image:Pa.gif]]


Google Company has made it a simple job but let ZK makes it even easier. We have integrated the Google Maps API into this ZK component, gmaps. And here is the example to write the same "Hello, World" of Google '''Maps'''.

<source lang="xml" >
<zk>
<script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=abcdefg"
    type="text/javascript"></script>
<gmaps width="500px" height="300px"/>
</zk>
</source>


The <script ...> references the same source of Google Maps API and all the other lines are wrapped into this '''gmaps''' component and you can control it by pure Java codes as other ZK components. Notice that the Google did some tricks on loading their Maps Javascript API codes. You have to [http://www.google.com/apis/maps/signup.html Sign up for the Google Maps API] to get your web site a key first; or you will not be able to access the Google Maps database. After getting the key, copy-paste to replace the abcdefg in the <script ... key=abcdefg">.

The Google API Key varies with the host server-name (e.g. you require one API-key while testing on localhost and a different one in production). Rather than hard-coding the API-key in the .zul file, you could set it as a session attribute and read it from there. To see how this can be set up, refer to the "initKey()" method in the class:org.zkoss.zkdemo.userguide.MainLayoutComposer.  Your .zul file may then contain a line like this:
<source lang="xml" >
<zk>
<script type="text/javascript" content="zk.googleAPIkey='${sessionScope.gmapsKey}'" unless="${empty sessionScope.gmapsKey}"/>
<gmaps width="500px" height="300px"/>
</zk>
</source>

The ZK team initializes the default latitude and longitude of the '''gmaps''' component to (37.4419, -122.1419), the Google's home. And you can of course change this by giving the '''gmaps''' component the new latitude(lat) and longitude(lng).

Following is an example that set maps center to, say (37.7765, -122.4140). Yes, it is San Francisco.

<source lang="xml" >
<gmaps width="500px" height="300px" lat="37.7765" lng="-122.4140"/>
</source>

[[Image:Sf.gif]]

=Map Movement and Animation=

The Google Maps API provides a javascript function GMap2.panTo to move the Maps center smoothly. The ZK team wraps that function into Gmap class as a java method, so you can control it by calling Gmap.panTo() Java method.


<source lang="xml" >
<zk>
<gmaps id="map" width="500px" height="300px"/>
<button label="panTo" onClick="map.panTo(37.4569, -122.1569)"/>
</zk>
</source>

[[Image:Panto.gif]]

Press the pantTo button and you should see the Maps slides to its northern-west side.


=Change the Zoom Level From Program=

The zoom level of the gmaps can be changed by program, too.

<source lang="xml" >
<zk>
<gmaps id="map" width="500px" height="300px"/>
<slider maxpos="17" curpos="${map.zoom}" onScroll="map.setZoom(self.curpos)"/>
</zk>
</source>

 [[Image:Zoom.gif]]   

sliding the bar and change the gmaps zoom level.


=Adding Controls to the Map=

The '''gmaps''' component also supports the three build-in controls, the GLargeMapControl, the GSmallMapControlG, and GMapTypeControl. You can control their visiblity by setting related attributes '''showLargeCtrl''', '''showSmallCtrl''', and '''showTypeCtrl''', repectively.

<source lang="xml" >
<gmaps width="500px" height="300px" showSmallCtrl="true"/>
</source>

[[Image:smallctrl.gif ]]

The Google Maps with a small control on the side.


=Event Listeners=

Besides controlling the behavior and size of the Google Maps view, listen to the Google Maps events is as important. The following example handles the onMapMove event(the "moveend" Javascript event) and show the new latitude and longitude of the new Maps center on the label.

<source lang="xml" >
<zk>
<gmaps id="map" width="500px" height="300px" showSmallCtrl="true">
    <attribute name="onMapMove">
    	center.setValue(""+self.lat+","+self.lng);
    </attribute>
</gmaps>
<label id="center" value="${map.lat},${map.lng}"/>
</zk>
</source>

[[Image:Onmove.gif]]   


Drag the map to a new location and see the latitude and longitude changes.

The following example shows how to handles the '''onMapZoom''' event and see what the current zoom level is.

<source lang="xml" >
<zk>
<gmaps id="map" width="500px" height="300px" showSmallCtrl="true">
    <attribute name="onMapZoom">
    	zoom.setCurpos(self.zoom);
    </attribute>
</gmaps>
<slider id="zoom" maxpos="17" curpos="${map.zoom}" onScroll="map.setZoom(self.curpos)"/>
</zk>
</source>

Press the zoom + , - button on the Small Control to see the slider bar moving.

[[Image:Onzoom.gif]]
    

=Summary=

We have demonstrated how to use this new ZK '''gmaps''' component, the Google Maps component. The Google Maps API is a versatile API set. The ZK team will integrate more functions and events into the gmaps component so ZK application developers can control it easily.

We are going to discuss the "behind the scene" in another smalltalks about how this Google Maps API is integrated as a ZK '''gmaps''' component; especially how to route the Google Maps javascript event back to server as an ZK event. Sit tight.


<comment>http://docs.zkoss.org/wiki/Put_Google_Maps_In_Your_ZK_Application</comment>



[[Category:3rd Party Components]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}