Gmaps"

From Documentation
m (correct highlight (via JWB))
(25 intermediate revisions by 4 users not shown)
Line 4: Line 4:
  
 
*Demonstration: [http://www.zkoss.org/zkdemo/reporting/google_map Gmaps]
 
*Demonstration: [http://www.zkoss.org/zkdemo/reporting/google_map Gmaps]
*Java API: N/A
+
*Java API: [https://github.com/zkoss/zkgmapsz/releases in release zip]
 
*JavaScript API: N/A
 
*JavaScript API: N/A
 
*Style Guide: N/A
 
*Style Guide: N/A
Line 10: Line 10:
 
= Employment/Purpose =
 
= Employment/Purpose =
  
Components: <tt>gmaps, ginfo, gmarker, gpolyline, gpolygon, gimage, and gscreen.</tt>
+
Components: <code>gmaps, ginfo, gmarker, gpolyline, gpolygon, gimage, and gscreen.</code>
  
A <tt>gmaps</tt> is a maps component that wraps the famous Google Maps service that you can control it and embedded it in your ZK web application page in pure Java. Inside the <tt>gmap</tt>, you can manipulate your maps and add contents to the maps to create convenient locality related web application. You can add <tt>ginfo</tt> to represent an anchored information window for the maps. You can add multiple <tt>gmarker</tt>s to indicate a special location. You can add <tt>gpolyline</tt> and <tt>gpolygon</tt> to indicate a path or an area. You can also overlay <tt>gimage</tt> and <tt>gscreen</tt> to indicate very special places.
+
A <code>gmaps</code> is a maps component that wraps the famous Google Maps service that you can control it and embedded it in your ZK web application page in pure Java. Inside the <code>gmap</code>, you can manipulate your maps and add contents to the maps to create convenient locality related web application. You can add <code>ginfo</code> to represent an anchored information window for the maps. You can add multiple <code>gmarker</code>s to indicate a special location. You can add <code>gpolyline</code> and <code>gpolygon</code> to indicate a path or an area. You can also overlay <code>gimage</code> and <code>gscreen</code> to indicate very special places.
 +
 
 +
=Authentication=
 +
==API Key==
 +
'''Important:'''
 +
Since 2016 an [https://developers.google.com/maps/faq#keysystem API Key is mandatory] in order to use the gmaps API.
 +
The APIKey is defined as a global JS variable as in the examples below. Also check out the [[#Trouble Shooting|trouble shooting]] section.
 +
'''NOTE''': You'll have to upgrade to version '''3.0.4''' (older versions don't work anymore)
 +
 
 +
See [[#Example|Example]] below.
 +
 
 +
==Client ID==
 +
Alternatively you can specify a client-id using the '''client'''-property <code><gmaps client="YOUR_CLIENT_ID"/></code>
  
 
= Example =
 
= Example =
Line 19: Line 31:
 
[[Image:ZKComRef_Gmaps_Example.png]]
 
[[Image:ZKComRef_Gmaps_Example.png]]
  
 +
source code for gmaps version 3.0.4 (and above)
  
source code for gmaps version 2.x
+
<source lang="xml"  highlight="2">
 
 
<source lang="xml" >
 
  
 
  <window title="Gmaps Demo" border="normal" width="520px">
 
  <window title="Gmaps Demo" border="normal" width="520px">
<script type="text/javascript" content="zk.googleAPIkey='Your-Google-API-Key'"/>
+
<script type="text/javascript" content="zk.googleAPIkey='Your-Google-API-Key';"/>
  
 +
<!-- you may wish specify the version of google map api manually for some reason,
 +
use version="[version]" to do it.
 +
ex: <gmaps version="3.25" id="mymap" ... /> -->
 
<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
 
<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
 
<ginfo id="myinfo" open="true">
 
<ginfo id="myinfo" open="true">
Line 50: Line 64:
 
</source>
 
</source>
  
  source code for gmaps version 3.x
+
  source code for gmaps version 2.x
  
 
<source lang="xml" >
 
<source lang="xml" >
  
 
  <window title="Gmaps Demo" border="normal" width="520px">
 
  <window title="Gmaps Demo" border="normal" width="520px">
<!-- you may wish specify the version of google map api manually for some reason,
+
<script type="text/javascript" content="zk.googleAPIkey='Your-Google-API-Key'"/>
use version="[version]" to do it.
+
 
ex: <gmaps version="3.5" id="mymap" ... /> -->
 
 
<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
 
<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
 
<ginfo id="myinfo" open="true">
 
<ginfo id="myinfo" open="true">
Line 80: Line 93:
 
  </window>
 
  </window>
 
</source>
 
</source>
 
  
 
= Properties =
 
= Properties =
Line 86: Line 98:
 
  since 3.0.0
 
  since 3.0.0
  
Specify which protocol to load the Maps API. Currently it supports <tt>http</tt> for insecure connections and <tt>https</tt> for secure connections.
+
Specify which protocol to load the Maps API. Currently it supports <code>http</code> for insecure connections and <code>https</code> for secure connections.
 
<!--
 
<!--
 
https://code.google.com/p/zkgmapsz/issues/detail?id=3
 
https://code.google.com/p/zkgmapsz/issues/detail?id=3
Line 93: Line 105:
 
=Supported Events=
 
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| <center><tt>onSelect</tt></center>
+
| <center><code>onSelect</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.SelectEvent</javadoc>
 
Notifies one that the user has selected a new item(can be [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Ginfo | Ginfo]], [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolyline | Gpolyline]], or [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolygon | Gpolygon]]) in the gmaps.
 
Notifies one that the user has selected a new item(can be [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Ginfo | Ginfo]], [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolyline | Gpolyline]], or [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolygon | Gpolygon]]) in the gmaps.
 
|-
 
|-
| <center><tt>onInfoChange</tt></center>
+
| <center><code>onInfoChange</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/InfoChangeEvent | InfoChangeEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/InfoChangeEvent | InfoChangeEvent]]
  
Line 107: Line 119:
  
 
|-
 
|-
| <center><tt>onMapDrop</tt></center>
+
| <center><code>onMapDrop</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/MapDropEvent | MapDropEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/MapDropEvent | MapDropEvent]]
  
Line 113: Line 125:
  
 
|-
 
|-
| <center><tt>onMapClick, onMapDoubleClick, onMapRightClick</tt></center>
+
| <center><code>onMapClick, onMapDoubleClick, onMapRightClick</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/MapMouseEvent | MapMouseEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/MapMouseEvent | MapMouseEvent]]
  
Line 119: Line 131:
  
 
|-
 
|-
| <center><tt>onMapMove</tt></center>
+
| <center><code>onMapMove</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/MapMoveEvent | MapMoveEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/MapMoveEvent | MapMoveEvent]]
  
Line 125: Line 137:
  
 
|-
 
|-
| <center><tt>onMapTypeChange</tt></center>
+
| <center><code>onMapTypeChange</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/MapTypeChangeEvent | MapTypeChangeEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/MapTypeChangeEvent | MapTypeChangeEvent]]
  
Line 131: Line 143:
  
 
|-
 
|-
| <center><tt>onMapZoom</tt></center>
+
| <center><code>onMapZoom</code></center>
 
| '''Event:''' [[ZK_Component_Reference/Events/MapZoomEvent | MapZoomEvent]]
 
| '''Event:''' [[ZK_Component_Reference/Events/MapZoomEvent | MapZoomEvent]]
  
Line 141: Line 153:
 
=Work with MVVM=
 
=Work with MVVM=
  
 +
'''3.0.4 already includes the <code>addon.xml</code> below''', you don't need to add it manually.
  
  
Line 305: Line 318:
 
=Supported Children=
 
=Supported Children=
  
  *[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Ginfo | Ginfo]], [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gmarker | Gmarker]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolyline | Gpolyline]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolygon | Gpolygon]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gimage | Gimage]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gscreen | Gscreen]]
+
  *[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Ginfo | Ginfo]], [[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gmarker | Gmarker]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolyline | Gpolyline]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gpolygon | Gpolygon]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gimage | Gimage]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gscreen | Gscreen]],[[ZK_Component_Reference/Diagrams_and_Reports/Gmaps/Gcircle | Gcircle]]
 +
 
 +
=Trouble Shooting=
 +
Starting from June 2016, an API key is required to use Google Maps APIs. If you are seeing the following error in your JS console, please obtain an API key from Google.
 +
 
 +
    Google Maps API error: MissingKeyMapError
 +
 
 +
For more information please refer to [https://developers.google.com/maps/pricing-and-plans/standard-plan-2016-update?utm_source=geoblog&utm_medium=social&utm_campaign=2016-geo-na-website-gmedia-blogs-us-blogPost&utm_content=TBC| this link].
 +
 
 +
Note that ZK GMaps integrates ZK and Google Maps, allowing developers to include Google Maps inside a ZK application easily. Google Maps itself is a 3rd party library and is licensed under its own terms and conditions.
  
 
=Use Cases=
 
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 320: Line 342:
 
{{LastUpdated}}
 
{{LastUpdated}}
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Revision as of 08:01, 18 January 2022

Gmaps

Employment/Purpose

Components: gmaps, ginfo, gmarker, gpolyline, gpolygon, gimage, and gscreen.

A gmaps is a maps component that wraps the famous Google Maps service that you can control it and embedded it in your ZK web application page in pure Java. Inside the gmap, you can manipulate your maps and add contents to the maps to create convenient locality related web application. You can add ginfo to represent an anchored information window for the maps. You can add multiple gmarkers to indicate a special location. You can add gpolyline and gpolygon to indicate a path or an area. You can also overlay gimage and gscreen to indicate very special places.

Authentication

API Key

Important: Since 2016 an API Key is mandatory in order to use the gmaps API. The APIKey is defined as a global JS variable as in the examples below. Also check out the trouble shooting section. NOTE: You'll have to upgrade to version 3.0.4 (older versions don't work anymore)

See Example below.

Client ID

Alternatively you can specify a client-id using the client-property <gmaps client="YOUR_CLIENT_ID"/>

Example

ZKComRef Gmaps Example.png

source code for gmaps version 3.0.4 (and above)
 <window title="Gmaps Demo" border="normal" width="520px">
	<script type="text/javascript" content="zk.googleAPIkey='Your-Google-API-Key';"/>

	<!-- you may wish specify the version of google map api manually for some reason, 
		use version="[version]" to do it.
		ex: <gmaps version="3.25" id="mymap" ... /> -->
	<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
		<ginfo id="myinfo" open="true">
			<![CDATA[
				Hello, <a href="http://www.zkoss.org">ZK</a>.
			]]>
		</ginfo>
		
		<gmarker id="mymark" lat="37.4410" lng="-122.1490">
			<![CDATA[
				Hello, <a href="http://www.zkoss.org">ZK</a> on top of Gmarker.
			]]>
		</gmarker>
		
		<attribute name="onMapClick">
			Gmarker gmarker = event.getGmarker();
			if (gmarker != null) {
				gmarker.setOpen(true);
			}
		</attribute>
	</gmaps>
 </window>
source code for gmaps version 2.x
 <window title="Gmaps Demo" border="normal" width="520px">
	<script type="text/javascript" content="zk.googleAPIkey='Your-Google-API-Key'"/>

	<gmaps id="mymap" width="500px" height="300px" showSmallCtrl="true">
		<ginfo id="myinfo" open="true">
			<![CDATA[
				Hello, <a href="http://www.zkoss.org">ZK</a>.
			]]>
		</ginfo>
		
		<gmarker id="mymark" lat="37.4410" lng="-122.1490">
			<![CDATA[
				Hello, <a href="http://www.zkoss.org">ZK</a> on top of Gmarker.
			]]>
		</gmarker>
		
		<attribute name="onMapClick">
			Gmarker gmarker = event.getGmarker();
			if (gmarker != null) {
				gmarker.setOpen(true);
			}
		</attribute>
	</gmaps>
 </window>

Properties

Protocol

since 3.0.0

Specify which protocol to load the Maps API. Currently it supports http for insecure connections and https for secure connections.

Supported Events

Name
Event Type
onSelect
Event: SelectEvent

Notifies one that the user has selected a new item(can be Ginfo, Gpolyline, or Gpolygon) in the gmaps.

onInfoChange
Event: InfoChangeEvent

Notifies that the current open information window has changed(opened/closed)

onMapDrop
Event: MapDropEvent

Notifies that some component is dragged and dropped on the gmaps or gmarker component with latitude and longitude information.

onMapClick, onMapDoubleClick, onMapRightClick
Event: MapMouseEvent

Notifies that some mouse action has been applied on the gmaps or gmarker component with latitude and longitude information.

onMapMove
Event: MapMoveEvent

Notifies that the view center (latitude, longitude) of the gmaps has been moved.

onMapTypeChange
Event: MapTypeChangeEvent

Notifies that the map type of the gmaps has been changed.

onMapZoom
Event: MapZoomEvent

Notifies that the zoom level of the gmaps has been changed.

Work with MVVM

3.0.4 already includes the addon.xml below, you don't need to add it manually.


since 6.0.0

For work with ZK6 MVVM, it is required to create an addon xml and add the server annotation as follows:


( You can download the sample project [here] )

WEB-INF/gmapsz-bind-addon.xml

<?xml version="1.0" encoding="UTF-8"?>
<language-addon>
	<!-- The name of this addon. It must be unique -->
	<addon-name>gmapszbind</addon-name>
	<!-- Specifies what other addon this depends
	<depends></depends>
	-->
	<!-- Which language this addon will be added to -->
	<language-name>xul/html</language-name>
	<!-- Add bind annotation to gmaps -->
	<component>
		<component-name>gmaps</component-name>
		<extends>gmaps</extends>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>mapType</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapTypeChange</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>LOAD_REPLACEMENT</attribute-name>
				<attribute-value>mapType</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>LOAD_TYPE</attribute-name>
				<attribute-value>java.lang.String</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>selectedItem</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onSelect</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>LOAD_REPLACEMENT</attribute-name>
				<attribute-value>selectedItem</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>LOAD_TYPE</attribute-name>
				<attribute-value>org.zkoss.zk.ui.Component</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>lat</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>lng</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>zoom</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapZoom</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>neLat</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>neLng</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>swLat</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
		<annotation>
			<annotation-name>ZKBIND</annotation-name>
			<property-name>swLng</property-name>
			<attribute>
				<attribute-name>ACCESS</attribute-name>
				<attribute-value>both</attribute-value>
			</attribute>
			<attribute>
				<attribute-name>SAVE_EVENT</attribute-name>
				<attribute-value>onMapMove</attribute-value>
			</attribute>
		</annotation>
	</component>
</language-addon>

then add it into WEB-INF/zk.xml

<zk>
	<language-config>
		<addon-uri>/WEB-INF/gmapsz-bind-addon.xml</addon-uri>
	</language-config>
</zk>

Supported Children

* Ginfo,  Gmarker, Gpolyline, Gpolygon, Gimage, Gscreen, Gcircle

Trouble Shooting

Starting from June 2016, an API key is required to use Google Maps APIs. If you are seeing the following error in your JS console, please obtain an API key from Google.

   Google Maps API error: MissingKeyMapError

For more information please refer to this link.

Note that ZK GMaps integrates ZK and Google Maps, allowing developers to include Google Maps inside a ZK application easily. Google Maps itself is a 3rd party library and is licensed under its own terms and conditions.

Use Cases

Version Description Example Location
     

Version History

Last Update : 2022/01/18


Version Date Content
     



Last Update : 2022/01/18

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.