History of GmapPackage
{maketoc}
!This Package is in Early Development
This package helps you include Google Maps for your bitweaver site and helps you manage and share content across your maps. It is being designed like wiki to enable collaborative development of Google Maps.
If you decide to test it out, note that updates are frequent, including database schema changes, so I wouldn't use it to build anything you want to keep at this point.
!!Special Installation Instructions
!!!Change the Directory Name
If you get the package from CVS it will come packaged in a dir named __map__. You must change it to __gmap__. A name change has been applied for to Sourceforge.
!!!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
The most important map component pieces are in place and undergoing testing. These include, map, marker, polyline, and map type editing. Styles for these are secondary and will come soon. 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.
__Next is to implement AJAX UI for creation and editing for:__
* Markers __(done)__
* Marker Sets __(done)__
* Marker Styles
* Icon Styles
* Polylines __(done)__
* Polyline Sets __(done)__
* Polyline Styles
* Map Types __(done)__
!!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
* There is some buggyness with Polyline rendering and it may be symptomatic of something else.
!!Other Next Steps
!!!Short Term Goals
* Get editing UI working Opera 8.5
* 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)
* Resolve bugs in current editing features.
** Multiple instances of same Marker are not updated when changed
** Engine does make use of z-index property of Markers
* 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)
* Wiki Syntax for all text
* Escape special characters etc for XML
!!!Long Term Goals
* Make auto map height possible
* Integrate other hack libraries (see map hacks below)
* Wikify the map and markers
!! Some other notes about developing the Gmap Package
Gmap was originally written using the Prototype js library. It has since been written out due to concerns as expressed on this site: [http://blog.metawrap.com/blog/PermaLink,guid,42b961d5-b539-4d9a-b1e0-108e546ae3e6.aspx|this issue with Prototype]. The methods using Protoype have been re-written using [http://mochikit.com|Mochkit]. Compatibility with basic javascript remains a concern, although Mochikit is looking reliable. All references to Mochikit are currently contained in one file: gmap/templates/formsubmit.js incase another change is needed.
You can get the latest version of the package by getting module _bit_map 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 Stumbling Blocks
* 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
!!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.
!!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://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]
!!Some Other Useful Stuff
!!!Bitweaver Stuff
*[http://81.138.11.136:8080/bitweaverdocsPHP/|Bitweaver Class Tree]
*[http://www.bitweaver.org/wiki/TP-Structures|List of BW tables and structures]
*[http://81.138.11.136:8080/bitweaverdocs//////__filesource/fsource_kernel__kernelBitDb.php.html#a498|Built-in Database Query functions available from bw kernel]
!!!Programming Stuff
*((PrototypeDocumentation))
*[http://digir.sourceforge.net/nightly/DiGIRprov/lib/adodb/docs-datadict.htm|ADODB Data Dictionary for PHP]
*[http://www.howtocreate.co.uk/tutorials/index.php?tut=0&part=25|Javascript and Navigating the Dom Tree]
*[http://smarty.php.net/manual/en/language.escaping.php|Using Javascript with Smarty] and elegant solution.
*[http://en.wikipedia.org/wiki/Join_%28SQL%29|DB JOIN FAQ on Wikipedia]
*[http://rafb.net/paste/|Code Paste Board]
*[http://sunsite.mff.cuni.cz/MIRRORS/ftp.mysql.com/doc/en/CREATE_INDEX.html|Creating Indeces for your database tables] as declaired in schema_inc.php
*[http://www.bitweaver.org/wiki/ThemeTutorial#sourcecode|Modifying Smarty for Debugging HTML]
*[http://www.cs.tut.fi/%7Ejkorpela/forms/choices.html|Guide to HTML Forms]
*[http://my.opera.com/community/forums/topic.dml?id=108345|Opera 9 beta]
*[http://my.opera.com/community/customize/setups/|Opera Tools for Web Dev]
*[http://nontroppo.org/wiki/webdevtoolbar|Another Opera tool bar] and [http://nontroppo.org/wiki/MooseCSS|more]
----
!!How to set up your own custom package
This is stuff I have learned about creating packages for bitweaver while creating this GMap Package.
!!!Download the "Sample Package" from this site
!!!Setting up your database tables
Database (DB) Tables are defined in "schema_inc.php"
This file goes in your __admin__ folder. Each package has one of these.
Some conventions to follow when building these:
*use single quotes on DB table scheme defaults
*underscore between each word in table names
!!!Including tpl files in the page header
The bitweaver Kernel is set up to automatically include header information from all packages. Any information you want included in the HTML HEAD you put in a file named "header_inc.tpl" which goes in your package's _templates_ folder.
To create conditional header includes simply nest tpl files in the header_inc.php file. You can do this by using the this include code:
{CODE()}{ include file="bitpackage:yourpackagename/subheader.tpl"}
{CODE}
!!!Permissions
* permissions can only be 30 characters long
!!!Creating the dropdown and side panel menus
Each package has teplate file that has its menus. You need to explicitly declair what you want in a menu in your own template file. For an example see the wiki package menu_wiki.tpl which you can find at:
wiki/templates/menu_wiki.tpl
!!!Preferences
Preferences are automatically created the first time you submit a value for one. This means that a preference can be created for the first time by simply submiting one via a form on the admin_sample.tpl. For more advanced preferences examples look at admin_wiki.tpl or admin_articles.tpl.
If you want to set default 'y' values for your package preferences during install, you declare these in the __schema_inc.php__ file in __admin__. You do not need to set a preference for any that you would give a 'n' value to.
The admin preferences panel is displayed via __/admin/admin_sample_inc.php__ usng the __template /templates/admin_sample.tpl__
Any prefereces set can be checked with __isFeatureActive()__
The admin menu is shown via __templates/menu_sample_admin.tpl__
!!Troublshooting Your Bitweaver Install
!!!Admin Locked Out
Try deleting your bowser cache and cookies for the site. Also try deleting from the database using the following:
{code}DELETE FROM `tiki_preferences` WHERE name ='cookie_domain';{/code} Do the same for cookie_path.
If those don't work, then try resetting the admin password to 'foobar' using this query:
{code}UPDATE users_users SET hash = md5( 'foobar' ) WHERE login = 'admin';{/code}
!This Package is in Early Development
This package helps you include Google Maps for your bitweaver site and helps you manage and share content across your maps. It is being designed like wiki to enable collaborative development of Google Maps.
If you decide to test it out, note that updates are frequent, including database schema changes, so I wouldn't use it to build anything you want to keep at this point.
!!Special Installation Instructions
!!!Change the Directory Name
If you get the package from CVS it will come packaged in a dir named __map__. You must change it to __gmap__. A name change has been applied for to Sourceforge.
!!!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
The most important map component pieces are in place and undergoing testing. These include, map, marker, polyline, and map type editing. Styles for these are secondary and will come soon. 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.
__Next is to implement AJAX UI for creation and editing for:__
* Markers __(done)__
* Marker Sets __(done)__
* Marker Styles
* Icon Styles
* Polylines __(done)__
* Polyline Sets __(done)__
* Polyline Styles
* Map Types __(done)__
!!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
* There is some buggyness with Polyline rendering and it may be symptomatic of something else.
!!Other Next Steps
!!!Short Term Goals
* Get editing UI working Opera 8.5
* 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)
* Resolve bugs in current editing features.
** Multiple instances of same Marker are not updated when changed
** Engine does make use of z-index property of Markers
* 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)
* Wiki Syntax for all text
* Escape special characters etc for XML
!!!Long Term Goals
* Make auto map height possible
* Integrate other hack libraries (see map hacks below)
* Wikify the map and markers
!! Some other notes about developing the Gmap Package
Gmap was originally written using the Prototype js library. It has since been written out due to concerns as expressed on this site: [http://blog.metawrap.com/blog/PermaLink,guid,42b961d5-b539-4d9a-b1e0-108e546ae3e6.aspx|this issue with Prototype]. The methods using Protoype have been re-written using [http://mochikit.com|Mochkit]. Compatibility with basic javascript remains a concern, although Mochikit is looking reliable. All references to Mochikit are currently contained in one file: gmap/templates/formsubmit.js incase another change is needed.
You can get the latest version of the package by getting module _bit_map 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 Stumbling Blocks
* 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
!!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.
!!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://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]
!!Some Other Useful Stuff
!!!Bitweaver Stuff
*[http://81.138.11.136:8080/bitweaverdocsPHP/|Bitweaver Class Tree]
*[http://www.bitweaver.org/wiki/TP-Structures|List of BW tables and structures]
*[http://81.138.11.136:8080/bitweaverdocs//////__filesource/fsource_kernel__kernelBitDb.php.html#a498|Built-in Database Query functions available from bw kernel]
!!!Programming Stuff
*((PrototypeDocumentation))
*[http://digir.sourceforge.net/nightly/DiGIRprov/lib/adodb/docs-datadict.htm|ADODB Data Dictionary for PHP]
*[http://www.howtocreate.co.uk/tutorials/index.php?tut=0&part=25|Javascript and Navigating the Dom Tree]
*[http://smarty.php.net/manual/en/language.escaping.php|Using Javascript with Smarty] and elegant solution.
*[http://en.wikipedia.org/wiki/Join_%28SQL%29|DB JOIN FAQ on Wikipedia]
*[http://rafb.net/paste/|Code Paste Board]
*[http://sunsite.mff.cuni.cz/MIRRORS/ftp.mysql.com/doc/en/CREATE_INDEX.html|Creating Indeces for your database tables] as declaired in schema_inc.php
*[http://www.bitweaver.org/wiki/ThemeTutorial#sourcecode|Modifying Smarty for Debugging HTML]
*[http://www.cs.tut.fi/%7Ejkorpela/forms/choices.html|Guide to HTML Forms]
*[http://my.opera.com/community/forums/topic.dml?id=108345|Opera 9 beta]
*[http://my.opera.com/community/customize/setups/|Opera Tools for Web Dev]
*[http://nontroppo.org/wiki/webdevtoolbar|Another Opera tool bar] and [http://nontroppo.org/wiki/MooseCSS|more]
----
!!How to set up your own custom package
This is stuff I have learned about creating packages for bitweaver while creating this GMap Package.
!!!Download the "Sample Package" from this site
!!!Setting up your database tables
Database (DB) Tables are defined in "schema_inc.php"
This file goes in your __admin__ folder. Each package has one of these.
Some conventions to follow when building these:
*use single quotes on DB table scheme defaults
*underscore between each word in table names
!!!Including tpl files in the page header
The bitweaver Kernel is set up to automatically include header information from all packages. Any information you want included in the HTML HEAD you put in a file named "header_inc.tpl" which goes in your package's _templates_ folder.
To create conditional header includes simply nest tpl files in the header_inc.php file. You can do this by using the this include code:
{CODE()}{ include file="bitpackage:yourpackagename/subheader.tpl"}
{CODE}
!!!Permissions
* permissions can only be 30 characters long
!!!Creating the dropdown and side panel menus
Each package has teplate file that has its menus. You need to explicitly declair what you want in a menu in your own template file. For an example see the wiki package menu_wiki.tpl which you can find at:
wiki/templates/menu_wiki.tpl
!!!Preferences
Preferences are automatically created the first time you submit a value for one. This means that a preference can be created for the first time by simply submiting one via a form on the admin_sample.tpl. For more advanced preferences examples look at admin_wiki.tpl or admin_articles.tpl.
If you want to set default 'y' values for your package preferences during install, you declare these in the __schema_inc.php__ file in __admin__. You do not need to set a preference for any that you would give a 'n' value to.
The admin preferences panel is displayed via __/admin/admin_sample_inc.php__ usng the __template /templates/admin_sample.tpl__
Any prefereces set can be checked with __isFeatureActive()__
The admin menu is shown via __templates/menu_sample_admin.tpl__
!!Troublshooting Your Bitweaver Install
!!!Admin Locked Out
Try deleting your bowser cache and cookies for the site. Also try deleting from the database using the following:
{code}DELETE FROM `tiki_preferences` WHERE name ='cookie_domain';{/code} Do the same for cookie_path.
If those don't work, then try resetting the admin password to 'foobar' using this query:
{code}UPDATE users_users SET hash = md5( 'foobar' ) WHERE login = 'admin';{/code}