From Documentation

• Author

  Henri Chen, Principal Engineer, Potix Corporation

• Date

  October 26, 2006

• Version

  Applicable to ZK 2.1.3.

Google Maps Version 2

Purpose

As has mentioned in the smalltalks Integrating FCKeditor, this is the second one that talks about how to wrap a pure Javascript component into a ZK component. In this article, the target to be wrapped as a ZK component is the famous Google Maps. If you are not familiar with the Javascript coding of the Google Maps, you can refer examples in this document.

Demo

http://www.zkoss.org/zkdemo/test/gmaps.zul

The source code, zk-GMaps-2.0-2006-10-20.zip, could be download here. If you are interested in developing ZK components, the source code provides the directory structure and necessary libraries and tools to build such components. If you are interested in how to use this Google Maps component only, you can see this smalltalks, Put Google Maps In Your ZK Applicaiton, and related ZKForge JavaDocs.

The four steps

To develope a Javascript component into a ZK component, we need to prepare four types of files.

• The lang-addon.xml file: Register the new ZK component.
• The Java files (*.java): Component as Java objects.
• The template files (*.dsp): Template to generate final HTML tags.
• The Javascript files (*.js): Glue logic to link the Javascript component to the Java class.

Register the new ZK component: the lang-addon.xml file

A new ZK component must be configured and registered in lang-addon.xml file such that ZK engine knows how to access and use it.

<language-addon>
	<!-- The name of this addon. It must be unique -->
	<addon-name>gmapsz</addon-name>
	<!-- Specifies what other addon this depends
	<depends></depends>
	-->
	...
	<component>
		<component-name>gmaps</component-name>
		<component-class>org.zkforge.gmaps.Gmaps</component-class>
		<mold>
			<mold-name>default</mold-name>
			<mold-uri>~./gmaps/gmaps.dsp</mold-uri>
		</mold>
	</component>
	...
</language-addon>

In the file we define the component-name to be gmaps. That is the zul tag name used in designing zul pages. The component-class is the ZK component class used by application developers. Each component can have multiple molds. Here we define only the default mold to gmaps.dsp, the template file to generate final HTML tags that will be read by the browser.

Component as a Java object: the Gmaps.java

Each ZK component is in fact a Twins. It is composed of the browser side Javascript and HTML codes and the server side Java classes. ZK as a server centric Ajax Framework, the Java APIs is like the face of the ZK component. A good set of APIs would help application developers to easily use the component. Of course, the definition of the APIs are naturally limited by what the original Javascript component can provide. Here we pick one as our example: The maps zoom level.

/** set zoom level.
 */
public void setZoom(int zoom) {
    if (zoom != _zoom) {
        _zoom = zoom;
        smartUpdate("z:zoom", ""+_zoom);
    }
}
 
/** get zoom level.
 */
public int getZoom() {
    return _zoom;
}

Send command from server to browser: the smartUpdate() method

Something interesting in the setZoom method is the smartUpdate. It is used by the ZK server to send command back to the browser in an Ajax response. The first argument of the smartUpdate is the attribute name or the command name. The second argument is a String that is the new value of the attribute or the associated data of the command to be sent to the browser. E.g. The smartUpdate("z:zoom", "10") will send z:zoom command along with the zoom level 10 to the browser and tells the Google Maps at the browser side to change zoom level to ten (10). Notice that for each http request, command with same name will be sent only once. Thus within one event handling (one XMLHttpRequest), if the Java API called the smartUpdate with same command name more than once, only the last one is sent.

mymap.setZoom(12);
mymap.setZoom(10);

E.g. The application developer calls setZoom(12) then setZoom(10) in event handling codes. Though the smartUpdate("z:zoom") is called twice, the Google Maps will not change zoom to 12 then 10 since the "z:zoom" command is sent only once with the last value. (It will zoom to 10 directly.) We have known the pitcher is the smartUpdate() method. Then who is the catcher in the browser side? It is of course the ZK Javascript engine. Then to where the ZK Javascript engine would route the command from the server? It is the key questions here. Before dig in the details of that, let us talk about the HTML tags generation mechanism first.

Generate the HTML tags: the gmaps.dsp

<c:set var="self" value="${requestScope.arg.self}"/>
<div id="${self.uuid}"${self.outerAttrs} z:type="gmapsz.gmaps.Gmaps">
</div>

zkGmaps.setAttr = function (mp, name, value) {
    switch (name) {
    case "z:zoom":
        mp._gmaps.setZoom(parseInt(value));
        return true; //command done, do not set attribute.
 
        ...
    }
    return false;
}

ZK component Gmaps.setZoom(10) 
  -> smartUpdate("z:zoom", "10") 
  -> (command response to browser)
  -> ZK Javascript Engine 
  -> zkGmaps.setAttr(mp, "z:zoom", "10") 
  -> Google Maps setZoom(10)

zkGmaps.init = function (mp) {
    if (GBrowserIsCompatible()) {
        //create the Google Maps and store it in the HTML node object
        var gmaps = new GMap2(mp);
        mp._gmaps = gmaps;
        ...
 
        //register the Google Maps event to Javascript handling functions
        GEvent.addListener(gmaps, "moveend", Gmaps_onmove);
        GEvent.addListener(gmaps, "zoomend", Gmaps_onzoom);
 
        ...     
    }
};
zkGmaps.cleanup = function (mp) {
    if (window.GMap2 != null) {
        ...
    }
};

zkGmaps.init = function (mp) {
    ...
    GEvent.addListener(gmaps, "zoomend", Gmaps_onzoom);
    ...
}

/** onMapZoom event hander */
function Gmaps_onzoom() {
    var gmaps = this;
    var mp = gmaps.getContainer();
    var uuid = mp.id;
    var comp = mp;
    var zoom = gmaps.getZoom();
    zkau.send({uuid: uuid, cmd: "onMapZoom", data: [zoom]},
    	 zkau.asapTimeout(comp, "onMapZoom"));
}

/*package*/ class MapZoomCommand extends Command {
    protected void process(AuRequest request) {
        final Component comp = request.getComponent();
        ...
 
        final String[] data = request.getData();
 
        //update the zoom level of the Gmaps component
        final Gmaps gmaps = (Gmaps) comp;
        final int zoom = Integer.parseInt(data[0]);
        gmaps.setZoomByClient(zoom);
 
        //post onMapZoom event to ZK event queue
        Events.postEvent(new MapZoomEvent(getId(), comp, zoom));
    }
}

Google Maps zoomend event fired
  -> Javascript Gmaps_onzoom() event handler 
  -> zkau.send({uuid: uuid, cmd: "onMapZoom", data: [zoom]}, 
       zkau.asapTimeout(comp, "onMapZoom"));
  -> (command request to server)
  -> ZK Update Engine 
  -> MapZoomCommand.process(request)
  -> Events.postEvent(new MapZoomEvent("onMapZoom", comp, zoom));

public class Gmaps extends HtmlBasedComponent {
    ...
 
    //register the Gmaps related event
    static {    
        new MapZoomCommand("onMapZoom", Command.IGNORE_OLD_EQUIV);
    }
}