History of GmapPackage
{maketoc}
!R2 Alpha is Under Development
This package makes including Google Maps on your bitweaver site a snap! It makes the creation of maps, markers, lines, and other information just a matter of pointing and clicking. It also helps you manage and share content across your maps. It is being designed like wiki to enable collaborative development of Google Maps. More feature details are further below.
The R2 version is under construction and is a significant upgrade of the Alpha R1 version. The R1 version basically works though there are bugs and some tikiwiki syntax parsing issues. At this point the R2 version will not run. It is recommended that you only use R1 for testing and not anything you want to keep at this point. R2 is not apporpriate even for testing at this point.
!R2 Version Documentation
GmapPackage on R2 is undergoing a major overhaul. The primary change in R2 is that location date, lat/lng pairs, are being managed by the new GeoPackage service. In addition Gmap is also beiing writen to offer itself as a service to all content. In conjuction with the GeoPackage, this makes assigning a location to your wiki page, articles, blog posts, user preferences, etc a snap. Not yet in place, but planned for R2, GmapPackage will eventually let you view all located content on a google map. For example you will be able to look at the 20 most recent articles on a map.
!!Feature Changes in R2
R2 will NOT support the Xmaps Library. At this point the Xmaps library which was developed for V1 of the Google Map API has not been redeveloped for compatibility with V2 of the API. There for the features that Xmaps enabled will be disabled in the R2 version of this package.
!R1 Version Documentation
!!Special R1 Installation Instructions
!!!You must obtain a Google Map API Key for your site.
To use the package you need a key from Google. You can sign up for a key [http://www.google.com/apis/maps/signup.html|here] - it is quick and painless and best of all, Free. After you install the package and have your key, you can plugin your key value for your site in the Gmap preferences.
!!!Change the HTML Tag
This must be done to get polylines to render in IE. This rather sucks, but there is currently no way to change it via the package, so it must be done manually. Here is what you need to do. Copy kernel/templates/header.tpl to themes/force/header.tpl. In the new file then change the html tag to the following:
{code}<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">{/code}
!!Summary of Current State of Development
All basic Google Map features are now fully supported and editable via a AJAX UI. Also, the best supplemental libraries to Google Maps have been introduced and many features are now integrated and editable. Gmap Package now supports the GxMarker and [http://www.pixeldevelopment.com/pdmarker.asp|PdMarker], and the [http://xmaps.busmonster.com/documentation.html|XMaps] library. Also 600+ free custom icon images, as [http://mapki.com/index.php?title=Icon_Image_Sets|listed here] are also included with the package. Additionally, the Marker infoWindow text now utilizes whatever default syntax is used on your bw install, in most cases this means the infoWindow text uses tikiwiki text formating.
You can get the latest version of the package by getting module _bit_gmap from bitweaver CVS.
Sometimes a proof of concept is working at [http://www.wjamesphoto.com/bw/gmap/index.php?gmap_id=1|this link]...if you find its not working, I am probably actively testing code changes. If so, you can find me on the bitweaver channel. But I will try to keep it working between changes. -wjames5
!!Some Known Bugs - if you find more add it here please
* If you change the name of a maptype and it is the default on a map, the map will break when it loads if you dont change the default name of the map. The map default maptype should be keyed to the maptype_id not its name
* The Icon style editing is buggy, both in adding new icon styles and in updating existing ones.
* New Marker Styles may not be updated menu options.
* Some characters, particularly in titles are not properly escaped before being Posted in an AJAX exchange.
!!Next Steps
!!!Priority Goals
* __Create a bwGMap class to encapsulate all functions__
+ A mistake in not doing this in the first place, this is necessary to allow maps in blog and article posts, so that more than one map can be on a page. (as well as making the code clearer).
* Escape special characters etc for XML
* Plan for GMap v2 Upgrade
* Plan for Bitweaver R2 Upgrade
!!!Long Term Goals
* Make auto map height possible
* Add comments support to markers (with R2)
* Resolve bugs in current editing features.
* Multiple instances of same Marker are not updated when changed
* Support both init Markers (markers that a plotted onload) and set Markers (markers that go into a menu but do not load on the map itself)
* Test editing UI in prior versions of Mozilla browsers
* Test editing UI in Safari 1.2.4+ (google maps is no compatible with lower versions)
* Engine does make use of z-index property of Markers - may remove this option from editing interface as it may be too complex for most users
* Support Wiki Syntax for text on the map page
* Get editing UI working Opera 8.5 - this moved to the end, because it may be unlikely
!Features
The Gmap Package supports all the basic Google Map features, markers, infoWindow balloons, custom icons, and polylines. It also supports the best of the hacks that supplement the Google Maps API, GxMarker, PdMarker, XMaps, and custom map types. With all these features you can create great looking maps without writing a single line of javascript. And with its "Sets Model", the Gmap Package makes it easy to re-use map components, like marker styles, custom icons, polylines, etc, over and over on mulitple maps, i.e. create once, use infinately. More about the "Sets Model" is below.
The features of the package are supplemented by a bleeding edge AJAX editing interface. Almost all features of the map can be updated live, without a browser refresh.
!! About the AJAX Editing UI
The Gmap Package has a very robust AJAX based editing interface for live updating of map features. The editing UI and related AJAX transaction methods use the [http://mochikit.com|Mochkit] library. All references to Mochikit are currently contained in one file: gmap/templates/js_edit_methods.js in case Mochikit ever becomes unreliable, or is discovered to have any conflicts with native javascript.
The editing interface is compatible with I.E. 6 and Firefox 1.5. and 1.0.7. The tools have been tested in Opera 8.5 but Opera is choking on a javascript process that copies data from an array into html forms.
!!Sets Model Framework
The GmapPackage uses a sets model for associating markers, markericons, maptypes, polylines, polygons, and their styles with maps.
Through the use of various keychains, each object may be associated with many maps, many sets of obejcts, and many styles. Each map has a key chain which associates it with sets of markers, maptypes, polylines, and polygons. Marker Sets, Polyline Sets, and Polygon Sets in turn each have individual objects as well as styles with which they are associated. The reason for this is multifold.
One advantage of this sets model is it makes it easier to share individual markers, polyline, and polygons with various maps and sets of each object. For example a marker can be in any number of sets, and those sets can be on any number of maps. This makes it much easier to share content across multiple maps. This could be especially value where say you might want to mash up particular information like restaurants, or art events with something universal like subway stops. Once you create a set of subway stops, then you could reuse that on multple maps mixing it with other data.
The other advantage is that styles can be divorced from content. This is both valuable for customizing the look and feel of the same map data on a map by map basis, as well as optimizing the database and lightening page weight. Each set contains a reference to a style. If a new look and feel is desired for a set of markers, that set only need be duplicated and a new style assigned. However none of the actual marker or polyline or polygon data is duplicated, only the reference to that data. This thus reduces redundancy while following in the W3C ideal of seperating data from style.
This use of sets also makes for lighter db queries and page weight. For each style used that style is only delivered to the client once, each object in a set then references that one style. This is faster and more efficient than packaging style information with each object...especially as one starts to use tens to hundreds of like styled objects on one map.
!!Development Goal
The goal of this project is to create a package that lets you edit a [http://maps.google.com|Google Map] like a wiki. In the distant future it would be nice to support XML importing and integration with Flickr.
Th package will take the best features of sites like [http://xmaps.busmonster.com/documentation.html|XMap Library]
[http://www.wikyblog.com|WikyBlog-Maps], [http://www.pixeldevelopment.com/virtualgoogleearth.asp|VirtualGoogleEarth], and [http://geobloggers.com|GeoBloggers] and merge them in to a package for hosting your own wikimap rather than having to use the existing services which are limited to their hosting, their feature implementation, and their look and feel.
If you want to join in I'm not a professional programmer, but have faith, this is going to be sweet, and spiderr is giving great guidance. If you do want to help out you should probably email me at wjames5 -at - nyc.rr.com or find me on irc #bitweaver before jumping in.
!!Code
You can get the latest stage of development by checking out ___bit_map__ from CVS HEAD branch.
!!Google Map Hacks to Include
*[http://xmaps.busmonster.com/documentation.html|XMap Library]
*[http://groups-beta.google.com/group/Google-Maps-API/search?hl=en&group=Google-Maps-API&q=GxMarker&qt_g=1&searchnow=Search+this+group|GxMarkers] Tools
*[http://gmaps.tommangan.us/tlabel.html|T-Labels]
*[http://www.pixeldevelopment.com/pdmarker.asp|PdMarker]
*Custom Map Tiles
*Geocoding
!!References
*[http://mapki.com/index.php?title=Knowledge_Base#Developer_Tools|Mapki Developer Tools]
*[http://www.google.com/apis/maps/documentation/|Official Google Maps API]
*[http://groups-beta.google.com/group/Google-Maps-API|Google Maps API News Group on Google Groups]
*[http://mapki.com]
*[http://www.flickr.com/services/api/|Flickr API]
*[http://www.flickr.com/services/api/key.gne|Flickr API Key Application]
!! Just Some Development Stumbling Blocks
These are not really anything to be concerned about if testing the map, mostly just some things about bw for me to learn.
* How to create admin features like the API key Spiderr put in.
* How to define features that get using like:
+ {code}$gBitSystem->isFeatureActive( 'feature_listMaps' ){/code}
* How to get Preference options set in Schema to show up as options in the package admin panel
---
Some random stuff for cleaning up the package
* creating onunload option in R1
+ in head there support is in a hash stored in $gBitSystem->mOnload;
!R2 Alpha is Under Development
This package makes including Google Maps on your bitweaver site a snap! It makes the creation of maps, markers, lines, and other information just a matter of pointing and clicking. It also helps you manage and share content across your maps. It is being designed like wiki to enable collaborative development of Google Maps. More feature details are further below.
The R2 version is under construction and is a significant upgrade of the Alpha R1 version. The R1 version basically works though there are bugs and some tikiwiki syntax parsing issues. At this point the R2 version will not run. It is recommended that you only use R1 for testing and not anything you want to keep at this point. R2 is not apporpriate even for testing at this point.
!R2 Version Documentation
GmapPackage on R2 is undergoing a major overhaul. The primary change in R2 is that location date, lat/lng pairs, are being managed by the new GeoPackage service. In addition Gmap is also beiing writen to offer itself as a service to all content. In conjuction with the GeoPackage, this makes assigning a location to your wiki page, articles, blog posts, user preferences, etc a snap. Not yet in place, but planned for R2, GmapPackage will eventually let you view all located content on a google map. For example you will be able to look at the 20 most recent articles on a map.
!!Feature Changes in R2
R2 will NOT support the Xmaps Library. At this point the Xmaps library which was developed for V1 of the Google Map API has not been redeveloped for compatibility with V2 of the API. There for the features that Xmaps enabled will be disabled in the R2 version of this package.
!R1 Version Documentation
!!Special R1 Installation Instructions
!!!You must obtain a Google Map API Key for your site.
To use the package you need a key from Google. You can sign up for a key [http://www.google.com/apis/maps/signup.html|here] - it is quick and painless and best of all, Free. After you install the package and have your key, you can plugin your key value for your site in the Gmap preferences.
!!!Change the HTML Tag
This must be done to get polylines to render in IE. This rather sucks, but there is currently no way to change it via the package, so it must be done manually. Here is what you need to do. Copy kernel/templates/header.tpl to themes/force/header.tpl. In the new file then change the html tag to the following:
{code}<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">{/code}
!!Summary of Current State of Development
All basic Google Map features are now fully supported and editable via a AJAX UI. Also, the best supplemental libraries to Google Maps have been introduced and many features are now integrated and editable. Gmap Package now supports the GxMarker and [http://www.pixeldevelopment.com/pdmarker.asp|PdMarker], and the [http://xmaps.busmonster.com/documentation.html|XMaps] library. Also 600+ free custom icon images, as [http://mapki.com/index.php?title=Icon_Image_Sets|listed here] are also included with the package. Additionally, the Marker infoWindow text now utilizes whatever default syntax is used on your bw install, in most cases this means the infoWindow text uses tikiwiki text formating.
You can get the latest version of the package by getting module _bit_gmap from bitweaver CVS.
Sometimes a proof of concept is working at [http://www.wjamesphoto.com/bw/gmap/index.php?gmap_id=1|this link]...if you find its not working, I am probably actively testing code changes. If so, you can find me on the bitweaver channel. But I will try to keep it working between changes. -wjames5
!!Some Known Bugs - if you find more add it here please
* If you change the name of a maptype and it is the default on a map, the map will break when it loads if you dont change the default name of the map. The map default maptype should be keyed to the maptype_id not its name
* The Icon style editing is buggy, both in adding new icon styles and in updating existing ones.
* New Marker Styles may not be updated menu options.
* Some characters, particularly in titles are not properly escaped before being Posted in an AJAX exchange.
!!Next Steps
!!!Priority Goals
* __Create a bwGMap class to encapsulate all functions__
+ A mistake in not doing this in the first place, this is necessary to allow maps in blog and article posts, so that more than one map can be on a page. (as well as making the code clearer).
* Escape special characters etc for XML
* Plan for GMap v2 Upgrade
* Plan for Bitweaver R2 Upgrade
!!!Long Term Goals
* Make auto map height possible
* Add comments support to markers (with R2)
* Resolve bugs in current editing features.
* Multiple instances of same Marker are not updated when changed
* Support both init Markers (markers that a plotted onload) and set Markers (markers that go into a menu but do not load on the map itself)
* Test editing UI in prior versions of Mozilla browsers
* Test editing UI in Safari 1.2.4+ (google maps is no compatible with lower versions)
* Engine does make use of z-index property of Markers - may remove this option from editing interface as it may be too complex for most users
* Support Wiki Syntax for text on the map page
* Get editing UI working Opera 8.5 - this moved to the end, because it may be unlikely
!Features
The Gmap Package supports all the basic Google Map features, markers, infoWindow balloons, custom icons, and polylines. It also supports the best of the hacks that supplement the Google Maps API, GxMarker, PdMarker, XMaps, and custom map types. With all these features you can create great looking maps without writing a single line of javascript. And with its "Sets Model", the Gmap Package makes it easy to re-use map components, like marker styles, custom icons, polylines, etc, over and over on mulitple maps, i.e. create once, use infinately. More about the "Sets Model" is below.
The features of the package are supplemented by a bleeding edge AJAX editing interface. Almost all features of the map can be updated live, without a browser refresh.
!! About the AJAX Editing UI
The Gmap Package has a very robust AJAX based editing interface for live updating of map features. The editing UI and related AJAX transaction methods use the [http://mochikit.com|Mochkit] library. All references to Mochikit are currently contained in one file: gmap/templates/js_edit_methods.js in case Mochikit ever becomes unreliable, or is discovered to have any conflicts with native javascript.
The editing interface is compatible with I.E. 6 and Firefox 1.5. and 1.0.7. The tools have been tested in Opera 8.5 but Opera is choking on a javascript process that copies data from an array into html forms.
!!Sets Model Framework
The GmapPackage uses a sets model for associating markers, markericons, maptypes, polylines, polygons, and their styles with maps.
Through the use of various keychains, each object may be associated with many maps, many sets of obejcts, and many styles. Each map has a key chain which associates it with sets of markers, maptypes, polylines, and polygons. Marker Sets, Polyline Sets, and Polygon Sets in turn each have individual objects as well as styles with which they are associated. The reason for this is multifold.
One advantage of this sets model is it makes it easier to share individual markers, polyline, and polygons with various maps and sets of each object. For example a marker can be in any number of sets, and those sets can be on any number of maps. This makes it much easier to share content across multiple maps. This could be especially value where say you might want to mash up particular information like restaurants, or art events with something universal like subway stops. Once you create a set of subway stops, then you could reuse that on multple maps mixing it with other data.
The other advantage is that styles can be divorced from content. This is both valuable for customizing the look and feel of the same map data on a map by map basis, as well as optimizing the database and lightening page weight. Each set contains a reference to a style. If a new look and feel is desired for a set of markers, that set only need be duplicated and a new style assigned. However none of the actual marker or polyline or polygon data is duplicated, only the reference to that data. This thus reduces redundancy while following in the W3C ideal of seperating data from style.
This use of sets also makes for lighter db queries and page weight. For each style used that style is only delivered to the client once, each object in a set then references that one style. This is faster and more efficient than packaging style information with each object...especially as one starts to use tens to hundreds of like styled objects on one map.
!!Development Goal
The goal of this project is to create a package that lets you edit a [http://maps.google.com|Google Map] like a wiki. In the distant future it would be nice to support XML importing and integration with Flickr.
Th package will take the best features of sites like [http://xmaps.busmonster.com/documentation.html|XMap Library]
[http://www.wikyblog.com|WikyBlog-Maps], [http://www.pixeldevelopment.com/virtualgoogleearth.asp|VirtualGoogleEarth], and [http://geobloggers.com|GeoBloggers] and merge them in to a package for hosting your own wikimap rather than having to use the existing services which are limited to their hosting, their feature implementation, and their look and feel.
If you want to join in I'm not a professional programmer, but have faith, this is going to be sweet, and spiderr is giving great guidance. If you do want to help out you should probably email me at wjames5 -at - nyc.rr.com or find me on irc #bitweaver before jumping in.
!!Code
You can get the latest stage of development by checking out ___bit_map__ from CVS HEAD branch.
!!Google Map Hacks to Include
*[http://xmaps.busmonster.com/documentation.html|XMap Library]
*[http://groups-beta.google.com/group/Google-Maps-API/search?hl=en&group=Google-Maps-API&q=GxMarker&qt_g=1&searchnow=Search+this+group|GxMarkers] Tools
*[http://gmaps.tommangan.us/tlabel.html|T-Labels]
*[http://www.pixeldevelopment.com/pdmarker.asp|PdMarker]
*Custom Map Tiles
*Geocoding
!!References
*[http://mapki.com/index.php?title=Knowledge_Base#Developer_Tools|Mapki Developer Tools]
*[http://www.google.com/apis/maps/documentation/|Official Google Maps API]
*[http://groups-beta.google.com/group/Google-Maps-API|Google Maps API News Group on Google Groups]
*[http://mapki.com]
*[http://www.flickr.com/services/api/|Flickr API]
*[http://www.flickr.com/services/api/key.gne|Flickr API Key Application]
!! Just Some Development Stumbling Blocks
These are not really anything to be concerned about if testing the map, mostly just some things about bw for me to learn.
* How to create admin features like the API key Spiderr put in.
* How to define features that get using like:
+ {code}$gBitSystem->isFeatureActive( 'feature_listMaps' ){/code}
* How to get Preference options set in Schema to show up as options in the package admin panel
---
Some random stuff for cleaning up the package
* creating onunload option in R1
+ in head there support is in a hash stored in $gBitSystem->mOnload;