GoogleMap v2.0

[1] What is GoogleMap?

INTRODUCTION

GoogleMap is a robust Google Map Pixelpost addon that puts a great amount of control in your hands. And most importantly:

It doesn't matter if your images have embedded GPS data or not.

The GoogleMap addon is a Pixelpost addon that allows the owner to give GPS locations to their images regardless if they have GPS equipment or not. The addon was created with the casual photographer in mind, who may or may not know much about GPS or even what it stands for!

The administration side allows the owner to navigate a Google Map and manually place a marker where each picture was taken. The GPS data of this marker is stored in the Pixelpost database and processed without any sticky conversions or in-depth knowledge. Once a photo has a location, it's ready to be shown on the main map that your viewers see.

GoogleMap is based upon the jbgMap (short for Jon Bulava's Google Map) written by Jon Bulava. This manual is also based on the text written by Jon Bulava and has been modified to reflect the changes in this new version.

THIS VERSION IS NOT COMPATIBLE WITH JBGMAP. IT WILL HOWEVER UPDATE EVERYTING TO REFLECT THE NEW STRUCTURE. YOU NEED TO CHANGE YOUR TEMPLATE TAGS AND YOU CAN'T GO BACK TO THE OLD ADDON!!!! READ THIS DOCUMENT CAREFULLY BEFORE INSTALLING!!!

[2] Installation - admin side

INTRODUCTION

There are two parts to install here: the admin side and the viewer side. Let's start with the admin side below.

STEP 01

Copy the files in the 'addon' folder located in the zip file to your 'addons' directory located on the root of your Pixelpost.

STEP 02

Place the complete folder (including subfolders and files) from the 'includes' directory located in the zip file in your 'includes' directory located on the root of your Pixelpost.

STEP 03

Note, the first time viewing this page, the new PHP file will add a column to your image table for Google Map coordinates and create a 'googlemap' table for storing settings.

Former users of the jbgMap addon are automatically transfered to the new database structure.

STEP 04

Now you need to obtain Google Map API keys from Google. They are long encrypted strings that track the map data used. These are directory specific so if you try copying one from someone else, sorry, it won't work. For this reason, you need one for your main Pixelpost link and one for the admin section. So basically, one for www.yourpixelpost.com and one for www.yourpixelpost.com/admin.

Once you have these, go to the 'Options' tab of your Pixelpost installation. There you'll find a new menu item called Googlemap, where all options can be set. Place the Google keys in the appropriate text fields on the options page and click 'Update Settings'.

STEP 05

At this point, all administrative settings should be functional. To make sure your admin API key works correctly, click the links to load the maps. You should see the default zoom and center displaying the entire United States. Feel free to change settings at this point, but they and setting locations for individual photos are described in detail later on for better understandability.

[3] Installation - user side

INTRODUCTION This is where things can get complex depending on how much you know about Pixelpost. Don't panic, it's not bad. If you understand how to make/edit HTML and write CSS style, you'll have no problem. Either way, I'll try to make this as simple as possible for everyone.

STEP 01

You need to create a new template file for your main display map. The easiest way to accomplish this is to open one of the HTML files in the template you are currently using ('browse_template.html' for example), and save it as 'googlemap_template.html'. You will notice that pages, like browse, use tags which are replaced by PHP code later on. GoogleMap uses this same principle. I've created three tags for use in template files: <GOOGLEMAP>,<GOOGLEMAP_HEADER>, <GOOGLEMAP_LINK> and <PIC_TO_GOOGLEMAP>.

The first thing you have to do is place the <GOOGLEMAP_HEADER> tag somewhere between the <head>...</head> section of the template file. This will put all the necessary Javascript functions in the HTML HEAD.

The next step is to replace the middle div of the page with <GOOGLEMAP>. Use <center> tags if you want to center the map as shown below. (The code shown below is only an example and does not have to be the same as your situation.)


						<div id="page">

      					<span class="title">Browse Archive:</span><hr /><br />

      					<div id="browse" align="center">

      					<BROWSE_CATEGORIES>

      					<br /><br />

      					<THUMBNAILS>

      					</div>

      					</div>

with:


						<span class="title">Google Map: <SITE_TITLE></span><hr /><br />

      					<center>

      					<GOOGLEMAP>

      					</center>

STEP 02

If your template also has a navigation bar, use the <GOOGLEMAP_LINK> tag to add a link to this new (and other) template page. It contains the entire <a href> tag when replaced so, for example, adding the link would work like this:

Before:


						<span class="menu">

      					<a href="index.php" title="Return to Homepage">Home</a> |

      					<a href="<SITE_BROWSELINK>" title="Browse">Browse</a> |

      					<a href="index.php?x=about" title="About">About</a>

      					</span>

After:


						<span class="menu">

      					<a href="index.php" title="Return to Homepage">Home</a> |

      					<a href="<SITE_BROWSELINK>" title="Browse">Browse</a> |

      					<GOOGLEMAP_LINK> |

      					<a href="index.php?x=about" title="About">About</a>

      					</span>

The same goes for the <PIC_TO_GOOGLEMAP> tag. This contains the full link to the "View on Map" option. (More on the "View on Map" in section 7). When clicked the user is redirected to the location of the image, showing an info window at a predefined zoom (see section [7] ).

STEP 03

MOST IMPORTANTLY, we want to load the map automatically when the page loads. In order to do this, two onload/onunload functions need to be added to the body tag in the Googlemap template file.

Replace:


						<body>

With:


						<body onload="GoogleMapLoad()" onunload="GUnload()">

GoogleMapLoad() loads the map when going to the page and GUnload() is a Google function that cleans server memory and other behind the scenes stuff. If you already have an onload function, simply separate them with a semicolon:


						<body onload="someFunction();GoogleMapLoad();" onunload="GUnload()">

STEP 04 Once this is complete, go to your Pixelpost and take a look. Most likely, the map will be showing, but there may be some hidden style issues to deal with later (e.g. image transparency), but we won't run into this until we put some data on the map.

Congratulations! The GoogleMap addon is ready to go!

[4] Administration Settings

INTRODUCTION

Here is a description of all administrative settings located on the addons section.

GOOGLE MAPS
API KEYS:

These need to be acquired from Google in order to use their Google map technology. You will need to get a Google account if you do not have one already (G-Mail members obviously have an account). Go to http://www.google.com/apis/maps/ and click on 'Sign Up.' You will need one for the main Pixelpost directory and one for the admin directory (www.yourpixelpostsite.com AND www.yourpixelpostsite.com/admin).

API VERSION:

If Google should upgrade their API version, it can easily be changed here instead of editing all the JavaScript in the add-on code.

MAP SIZE:

This is the size of the map your visitors will see in pixels.

ZOOMLEVEL:

Another new option is the zoomlevel when the option "View on Map" is used. This option will take the user straight to the map, showing the location of the image. It is now possible to use a different zoom level (1 -> no zoom, 15 -> lots of zoom).

INITIAL
MAP STYLE:

The map type that your visitors will see when the page is loaded. The three types are:

MAP-Shows drawing and roads;
SATELLITE-global images;
HYBRID-Combination of the other two.

ICON STYLE
FOR MARKERS:

Markers are the objects used to mark the location of each image in your Pixelpost. You can choose from the default Google marker, an actual thumbnail image, or one of the custom markers. If you click the custom markers all available markers and sizes will be shown.

It should be noted that extra files are needed if the custom markers are selected. An additional transparent image is needed in order for clicking to be possible within info windows' shadows. These images are included in the download and reside in your 'includes/googlemap/' directory in the Pixelpost root directory.

ICON STYLE
FOR MARKER
LATEST PICTURE:

The latest picture added on the Googlemap can be marked by a different marker. The same principles as the markers mentioned above apply.

INFORMATION
TO DISPLAY IN
INFO WINDOWS:

Check what information you would like to show up in the map's info windows when a marker is clicked. Options include a linked thumbnail, headline, date, time, and categories.

DENOTE LOCATIONS
OF PREVIOUS IMAGES
IN EDIT SECTION:

In this version it is possible when placing a marker on the map for an image to see the other images on the admin map. Previous image locations are displayed by a small blue marker.

CLUSTERING
OF MARKERS:

Nearby markers can be clustered to one marker. Clustered markers can have their own style. If this option is selected additional settings become available.

ICON STYLE
CLUSTERS:

Clustered markers can have their own style as defined here. The same principles as the markers mentioned above apply.

OTHER SETTINGS
CLUSTERS:

Various other settings can be applied to the clustering routine to change the behaviour. Detailed information is given in the options page.

SET CENTER
AND
ZOOM LEVELS:

Use this section to set the default center and zoom levels of the edit-image map, which is used to set coordinates for each image, and also for the map that your visitors will see. Simply put the maps where you want them and click 'Update Settings.'

[5] Assigning a Location to an Image

INTRODUCTION

From version 1.5 support is added for Google Earth notation for langitude and latidude. All Google Earth notations are supported. If a notation is used which could not be translated an error message will be shown.

Note: All attempts to use the Google Map on addresses in the UK or China will currently fail indicating that legal or contractual reasons prevent Google from returning the information. This is not an issue with the addon but a Google issue.

A future version of this addon should include the usage of EXIF GPS tags if they exist to create the image's Google Map location. In the meantime, the 'Use EXIF Tags' button will not do much. This new functionality is difficult to test since I do not have the equipment personally, and therefore, no image examples either. I've recently acquired some that I believe will work, so this is my next item to add. The new Pixelpost version 1.6 will make this feature even easier.

STEP 01

To give an image a location, log into the administration page and click 'Images', then '[Edit]' for any existing image. The map addon creates a submenu item in this section titled 'GOOGLEMAP.' From this section, you may load the edit-view map and click where the image was taken (reset and deletion instructions are located on the page as well).

Note, when selected in the Administration Settings locations of previous image are visible in the edit-view map. Small blue markers denote the locations. It is not possible to change the location of these blue markers.

[6] The Viewer's Map

INTRODUCTION

Now that you have some photo locations marked, take a look at that template page that was created earlier (Presumably at www.yourpixelpost.com/?x=googlemap). THINGS MAY LOOK MESSY THE FIRST TIME AROUND. Don't worry, this is normally because the map inherits style from the page. Check out section [8] on style for more information.

The way this map works should be self-explanatory. Clicking on a marker will pop-up an info window and display the information you specified on the admin side of the addon. If you are displaying a thumbnail, clicking it will take you to its full size page.

Note, For future development, see section [11].

[7] The View on Map option

INTRODUCTION A new tag was introduced to facilitate this new option. When the <PIC_TO_GOOGLEMAP> is used on your image template it will be a link to the jbgmap template file with the photo's id as a passed value. If coordinates exist for this image, the info window will pop up automatically.

The <PIC_TO_GOOGLEMAPP> uses the language file to determine the name of the link. Since this is not part of a default Pixelpost installation please follow the instructions to add the correct variable to the language file.

STEP 01

Please open your default language file from the language folder. If your defaultlanguage is English please open language/lang-english.php.

Find the section called "// Month and Day", the last line of this section should be $lang_december = "december";

Now add the following section after "$lang_december = "december";":


						 // GOOGLEMAP

						       $lang_view_on_map = "View on Map";

If this variable is not found in the language files the addon reverts to the default text which is "View on Map".

STEP 02 Save your language file and upload it to your site.

[8] Style Info and Cascading Style Sheets

INTRODUCTION

Site style is inherited by the elements within the Google Map. Therefore, if you are using some of the CSS that comes with the Pixelpost download, or your own, it is possible for some conflicts to occur right away. For example, if a style definition like the one below is being used, you will have an issue with the backgrounds of Google map markers.


						#page img {

						   background:#fff;

						   padding:5px;

						   border:1px solid #333;

						}

This exact issue happened in my case. Here was my initial solution, however not that necessary, so just skip to the next paragraph if you don't get what I'm talking about. Since the above style appeared to only be used for thumbnails under the browse page, I first limited its scope by changing it to "#page #browse img" in both CSS files (light & dark, the template I'm using). Then I edited the browse template file to say '<div id="browse" align="center">' instead of '<div align="center">'. Problem solved (if you know what you are doing with style).

To lessen this kind of hacking to make the addon work, I used style IDs in the code that can be used in CSS files that you are currently using. Odds are you will have to do some tweaking using these below to get exactly what you want. They will inherit from predefined divs, imgs, and spans, but simply over-ride those effects by adding these to the appropriate CSS files.

`div#viewMap`	- Entire Map div
`div#GoogleMapInfoWindow`	- Google Map Info Window
`img#GoogleMapThumb`	- Thumbnail in Info Window
`span#GoogleMapHeadline`	- Headline in Info Window

Note, width and height of the entire map div are set on admin page and do not need to be changed via style. The same goes for the width and height of the thumbnails which are defined in the admin options.

IF YOU PREVIOUSLY USED THE JBGMAP ADDON YOU NEED TO MODIFY YOUR STYLE.CSS FILE, LOCATED IN THE TEMPLATE DIRECTORY YOU USE!!

EXAMPLE

Here is an example of style that may be useful; it's what I use.

						
						div#viewMap {

      					   border: 1px solid #333333;

    					}


    					div#GoogleMapInfoWindow {

    					   width: 250px;

    					   height: 75px;

    					   text-align: left;

    					   color: #333333;

    					}


    					img#GoogleMapThumb {

    					   border: 0;

    					   margin: 0px 5px 0px 0px;

    					}


    					span#GoogleMapHeadline {

    					   font-weight: bold;

    					}

[9] Uninstalling jbgMap

INTRODUCTION

Currently there is no user-friendly way of deleting this addon. I spent so much time writing it, I never thought that someone may want to delete it! However, here is a checklist of things you need to manually delete.

Files:

`'admin_GoogleMap.php'`	- In addons folder
`'googlemap_template.html'`	- In your template folder
`'googlemap' directory`	- Directory in 'includes' directory

Database data:

`'GoogleMap'`	- Table which contains setting information
`'GoogleMap' COLUMN in 'pixelpost' table`	- ATTENTION! THIS IS WHERE ALL YOUR IMAGE DATA IS. MAKE SURE YOU ONLY DELETE THIS COLUMN AND NOT THE WHOLE TABLE.

Note, if you are not familiar with database administration, just leave these items floating in your database until I release another version that may do this for you.

[10] Some Known Issues

INTRODUCTION	You will find a list of know issues bellow. This list may change from time to time depending on the release of newer versions of GoogleMap.
ISSUES	1 - No transparency behind map markers. See Style Information section 2 - The space for the map appears, but the map doesn't load. Make sure that you have placed the onload and unload functions in the body tag of your map template file. `<body onload="GoogleMapLoad()" onunload="GUnload()">`

[11] Future development

INTRODUCTION

If you have any ideas not listed bellow that may make this map addon more useful, please feel free to email at schonhose@gmail.com.

FUTURE DEV

1 - New tag: GOOGLEMAP_LIST
      A possible extension to be placed under the main display map that will
      show either an entire list of titles or set of thumbnails of those images
      with coordinates. I might include this as an option on the admin side
      instead of a tag to simplify things.

2 - Limiting the pictures on the map to a specified category.
      (similar to the browse page) map also be in the works.

3 - Get coordinates from EXIF
      If the EXIF has GPS coordinates the addon will recognize this and show
      the location on the map.

[12] Version History

INTRODUCTION

Key:
[!] Important
[+] New
[-] Fixed error
[*] Changes

Note: I have made many bugfixes and improvements to the original code. As of version 2.0 I decided to release this improved version under a different name. Consequently all references to the old jbgMap addon have been removed. The new GoogleMap addon is not compatible with the old jbgMap addon (e.g. database and tags). However, the new addon detects the presence of the old database and will convert it.

HISTORY Update to version 1.0a, 1.0b and 1.0c
[-] Fixed the unable to save settings bug
[-] Pictures not published yet are not shown on the map
[+] Added an address search option in the admin section
[*] Made all output HTML 4.0 strict compliant
[+] New tag: <PIC_TO_GOOGLEMAP> for showing the location of the picture
[+] Locations of previous images can be seen when editting the location of an image
[+] Adjustable zoomlevel when showing the location of the picture.
[+] Added language file support
[*] Bigger map in the admin section
[-] The map is now automatically loaded when searching for an address

Update to version 1.5:
[-] Forgot an item for the save settings bug.
[+] Possibility to type in latitude and longitude (Google Earth notations)
[+] Placing a marker shows latitude and longitude (Google Earth notations)
[-] Showimage option is now working with thumbnails
[-] Special characters in title or description needed to be escaped
[+] Special debug information
[*] Determine the path to the thumbnail images
[*] Rounded output of Thumbnail width and height

Update to version 2.0:
[!] Changed the name to GoogleMap addon, not compatible with the old jbgMap addon
[-] Fixed another item in the save settings bug.
[+] Version variable for debugging purposes.
[-] Closing of certain HTML elements
[*] Options stuff moved to the Options workspace and cleaned up
[+] New tag for template file to move all javascript in the HEAD section
[+] Latest marker is always on top of the others (e.g. added order of creation)
[+] Added a possibility to use custom markers with predefined sizes
[+] Newest thumbnail can be shown on map with different marker
[*] Removed the small marker (is now supported by the custom markers)
[+] The edit map is set to the size of the viewers map
[+] Below the map a carousel is displayed, clicking on thumbnail shows info on map
[+] Export feature to downloadable KML file, show custom markers in Google Earth
(accesible through index.php?x=googlemap&action=kml
[+] Wheelmouse and doubleclick zoom support in viewers and edit map
[-] Removed postionOverview function. It seems to be doing nothing.
[+] Map now shows the Google Map scale.
[+] Markers can be grouped or not based on various settings Grouped marker can be
default or custom.
[+] Grouped markers can be displayed by default or custom icon.