Gallery2:Modules:Map:UserGuide

Back to Gallery2:Modules:Map

This is intended to be a complete user and administrator guide to the Google Map module for Gallery 2. The module has become quite complicated, and hopefully this guide will be useful to both new users and long-time users exploring new features.

Please feel free to add to this guide! If you're unsure about a feature or would like feedback on a contribution, you are welcome to contact one of the team members.

This guide does not cover the theme version in detail. For more information on using the theme, see Gallery2:Themes:Map.

Note: This guide currently refers to map version 0.4.9 and above; please upgrade to the latest working versions.

Requirements

These requirements refer to both the module and the theme.

A working Gallery 2.x installation. You don't need photos, but with no photos, you will not get any useful information in your map.
A Google Maps API key, which is freely available and can be requested here.

Some modules are optional and provide more features. These modules are available at the module download page.

ImageMagick is required for some features to work.
EXIF module version 1.0.1 or higher is needed for EXIF features.

Installation

You can now install via downloadable plugins: How to Install Plugins

Quick Configuration Guide

Heres a fast way to get the basic features installed and running, more advanced features are discussed below.

1. Install via downloadable plugins: How to Install Plugins

2.Go to your Gallery Site Admin > Admin Options > Plugins and click install then click configure.

note: If you get an error here its most likely you dont have the exif module installed

3.Click which version of google api you want to use (google has updated thier api recently to version 2.x but at this writing ..28 February 2006.. version 1.x is more stable)

4. Add your profile in..click the add profile button

- enter a name
- enter you web sites url
- enter your web sites port, leave this blank in most cases.
  - The latest SVN version of the map module does not pass port numbers properly to the google api-key sign up page. The current workaround is to visit http://www.google.com/apis/maps/signup.html and generate a key using the form found there. This is only an issue if your host is on a port other than 80. For example if yourhost.com resides on port 443 visit the google url and enter http://yourhost.com:443 to generate your key. Copy and paste your key into the appropriate box in the map configuration page.
- enter your unique google api key that you need to get Here

Your web sites url needs to be the correct path and in most cases should be your top level domain name. For sites with 2 urls like ://example.com and ://www.example.com add 2 profiles, one for each with the same google api key. There are more referance examples at the bottem of this page.

5. Hit save when your done

6. Return to the list of modules in Gallery administration. Click "activate" on the Google Module.

7. Navigate to one of your gallery photos or albums and click "edit item" from the "item actions", you should now see a google maps tab in the menu

8. Click the google maps link and enter the gps for the photo/album manually, via the "get via map option" or the "get via address".

The "get via map" enables you to load the map and save the co-ordinates with 1 click when you find the right spot on the map.

9. Hit "save" when you have proper co-ordinates

Your done:) your first photo/album should now appear on the map
Browse over to your gallery and click on the "view item on the map" link in the menu, if the map loads with your picture on it your all set. Repeat these steps to add as many photos/albums as you want.

Advanced Usage

Specific settings to each album/photos

Where: Edit Item (or Edit Album) => "Google Map" Tab.
What:

GPS coordinates

Can be entered Manually in the format longitude, Latitude
Point and click, click on a google map autofill the GPS coordinate on save
Can be found via an address
- This feature uses a built-in function that gets the coordinate from the Google Local system
Can be populated via EXIF information in the picture

Zoomlevel

This is the Zoom level used when the Zoom In link is clicked (Zoom in Links are enable via the Admin Panel)

Color

Choice of color depends on the Marker Set selected
The color selected for an Album can be set as default to all it's children (via the Admin Panel) +

Support for the Rewrite module

Where: AdminPanel -> URL Rewrite (URL Rewrite Administration) - Rules tab
What:
There is a rule created to make the map visible via http://whereismygallery/map/
To enable it or change it, go to the Rewrite Module Admin Panel (assuming it's installed)

Marker Set management

Where: AdminPanel -> Google Map - Theme Settings Tab
What:

View all Available Markers
- Shows a new page with all the Markers Created and Available for use with the Map
Add a MarkerSet
- Let's you create a new MarkerSet from withing the module (rely on ImageMagick)
- Select a base icon to create the other ones
- You can upload new icons with a redish color to be a base
- Uses ImageMagick "convert" utility to varie Hue and Saturation to creates other color
- There is also the possibility to create only certain colors as opposed to all
- You can adjust the size of the created markers
- A Unique name need to be used for that Marker Set to easily identify it
Delete a MarkerSet
- The MarkerSet currently selected in the dropdown will be deleted without any warning :-)
- It can always be re-created (granted that you have ImageMagick) via the Add button.
Select a Default marker and color
Pretty self-explanatory
You can select a different marker set for photos and album to differenciate them
You can also select a default color. The default color will apply to all item without a selected color
Use parent album color
This will override the "default photo color" in each album
It will use the color selected for that album for each item in it that has not color specified

Automatic Regrouping

Where: AdminPanel -> Google Map - Theme Settings Tab
What:

Automatic Album based Regroup
- When item are too close to their parent album, only the parent album is shown
- You get the Album Icon and when you click on it it displays all the children
- When all children are displayed, the parent marker is hidden
Automatic Item regroup
- You select a distance in pixel (Item regroup distance)
- All item closer than the distance selected are hidden
- A special marker is displayed instead
- You can upload new icons for this specific purpose
- A marker must be selected for this to work :)
- When you click on the icon, it zooms in and show more details on the map area

General Theme Settings

Where: AdminPanel -> Google Map - Theme Settings Tab
What:

Map Control Size / Type
- This let's you choose the type of Map Control you want displayed on the Map
- "Stock" are the built-in Google Map controls (white stuff)
- Large controls have a long zoom bar and "go back to the last result" button
- Small are the minimal controls
- Other than stock let's you display the picture you'd like instead of those basic white ones.
- The module comes with a cretain number
- You can create your own:
  - Create a new folder under modules/map/templates/controls/
  - Copy a control.inc file from another folder
  - Put all of the png file you wish to use on your map
  - Open the control.inc file and change the name of the PNG files
  - Select your new template on the dropdown box on the Admin Panel (refresh if necessary)
Infowindow Templates
- Those are templates to use for the infowindow aspect
- You can have a single window or a tabbed window
- You can also create you own
  - If you wish to create a tabbed window, copy tabbed.inc
  - If you want a simple windw, copy default.inc
  - Open the files and add/remove what you need.
  - You can experiment as much as you want
  - If you need help you can come on the forum and ask for help

GZoom

Where AdminPanel -> Google Map - GZoom Settings Tab
What

The GZoom tool is developped by Andre Lewis, you can get more information about the extension here
GZoom is a custom Google Maps control which allows you to zoom by dragging a rectangle on the map.

Routes Feature

Where AdminPanel -> Google Map - Routes Management Tab
What
Routes is a way to create Polyline on the Google Map using the icon with GPS coordinates

A route is a set of the following item:
Name
- Anything you want really, but it's mandatory
Color
- Color is not mandatory. If not selected, it will use the default Google Color (blue-purple)
- A color picker is provided for easy selection
Size
- The size is not mandatory. If not entered it will default to 3 pixels
- It's the thickness of the polyline in pixels
Opacity
- It is not mandatory. If not selected it will default to 1
- It's a number between 0 and 1.
- 0 is completely invisble, 1 is not transparent at all.
- It's a nice way to let things below be visible if needed
Items in Route
- This displays all of the item in your gallery that have GPS coordinate (the list can be long)
- You need to select at least 2 different one to make a polyline
- You are allowed to select the same item several time by entering positions separated by commas
You can also choose whether the route is enable or not
You can also choose to create a filter from the route or not
- The filter is not actually created at this point
- It will be automaticaly generated when the "Filter" block is shown by the map
- The filter will Auto Center and Zoom on the markers composing the route

AutoCenter and Zoom

Where AdminPanel -> Google Map - General Settings Tab
What

TBD

Filter features

Where AdminPanel -> Google Map - Group/Filter management Tab
What

TBD

Legend feature

Where AdminPanel -> Google Map - Legend management Tab
What

TBD

Other general features

Where AdminPanel -> Google Map - General Settings Tab
What

TBD

Google Map - General Settings Tab
- The Map Key Management Feature

A new feature has been added to The Module that allows for multiple map keys to be created (these are called Profiles). The Module will automatically choose the appropriate key depending on the Server Name and Server Port number. In it's simplest form, two keys could be created with the same Server Name; but, different Port numbers (ie: 80 and 443).

Setup
In Site Admin/Google Map/Map Module Settings/General Settings' you will find Google Map Key Profile:. Here you will find a drop-down box and two buttons, Add Profile and Delete Profile.

Click the Add Profile button and a new page will be displayed with four entry boxes:

1. Name for the Profile: Type any name you wish (ie: myhost_80 or myhost_443)

2. Server Name (e.g. www.myserver.com): Here you enter you web server's name. This may or may not be the base URL that you use to access your web site.
NOTE: A simple way to find out what you should enter here would be to do the following:

(a) Edit ShowMap.inc
(b) Just after the first line in ShowMap.inc
- First line:

<?php

- Add the following

$serverName = GalleryUtilities::getServerVar('HTTP_HOST');
$serverPort = GalleryUtilities::getServerVar('SERVER_PORT');
print ("serverName = $serverName<br>");
print ("serverPort = $serverPort<br>");

NOTE: Adding this will probably cause some formatting irregularities in page that is displayed; but, it will not harm anything,

(c) Now access your map. At the top of the page you will see the reported server name and the server port number. Record this information and then remove (or comment out by placing two forward slashes // in front of the added lines) the lines in ShowMap.inc that you added above.

Now add the reported server name in the Server Name (e.g. www.myserver.com): entry box.

3. Port Number (e.g. 80 , 443, ...): Add the server port number that was reported (using the method above) here

4. Google Map Key: Add the map key that you obtained from Google (here) in this entry box

NOTE: Most would want to obtain a map key for the top level of their web site.
-For example:
-If your map page URL is:

http://www.mymaphost.com/gallery/main.php?g2_view=map.ShowMap

-get a key for

http://www.mymaphost.com/

-this would cover any and all directories/URLs within this web site (including your map whether or not your map is accessed via /gallery/ or /gallery2/ or ???)

-Now for a confusing map key possibility-
-If your server name is reported using the method above as www.mymaphost.com

but you actually use

http://IP_ADDRESS/gallery/main.php?g2_view=map.ShowMap

to access your map, you would need to generate you map key using

http://IP_ADDRESS/

and NOT the reported server name. You would -still- use the reported server name in the 'Server Name (e.g. www.myserver.com):' entry box ( -NOT- the IP_ADDRESS).

This is because the automatic lookup of the map key is done using the reported server name (and server port number) and not the URL(IP_ADDRESS) you use to access your map. The map key is tied to the URL and not the server name.

Also of note here is that, although it is possible to make two entries in Map Key Management with the same server name under different Profile names, Only one (I suspect the first one that is found) will be used. So you cannot have an entry (Profile Name: myhost_domain_name) using a map key that was generated for a domain name URL -and- an entry (Profile Name: myhost_IP) using a map key generated for an IP address both using the same server name. Only one will be used when you access the map and the other will generate a Google Map Key complaint.

An example of all this

Profile Name: myhost_80
Server Name: www.myhost.com
Port Number: 80
Google Map Key: ABCD_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: myhost_443
Server Name: www.myhost.com
Port Number: 443
Google Map Key: DCBA_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: myhost_IP_80
Server Name: myhost
Port Number: 80
Google Map Key: ZYXW_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: myhost_IP_443
Server Name: myhost
Port Number: 443
Google Map Key: WXYZ_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

-- This one will (or the one above with server name=www.myhost.com) be ignored because the server names are identical
Profile Name: myhost_IP_80_dom
Server Name: www.myhost.com
Port Number: 80
Google Map Key: GHIJ_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: anothervirtualhost_80
Server Name: www.virtualhost.com
Port Number: 80
Google Map Key: JKLM_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: anothervirtualhost_443
Server Name: www.virtualhost.com
Port Number: 443
Google Map Key: MNOP_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: yetanothervirtualhost_80
Server Name: www.virtualhost2.com
Port Number: 80
Google Map Key: RSTU_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

Profile Name: yetanothervirtualhost_443
Server Name: www.virtualhost2.com
Port Number: 443
Google Map Key: TUWX_EFGHIJKLMNOPQRSTUVWXYZ (Fake key used here)

I have tried to explain this as best I could; but, my brain does not necessarily work (and probably does not :-) ) the same as anybody elses, so please feel free to add/subtract/emphasize any or all parts of this.

A Couple Notes about the Upgrade path

from v0.3.2 (and below) to v0.4.0 and later
- Rewritten part of the module to make it independant of CustomField module, in order to work you have to do following steps:
1. Export the content of the table called g2_customFieldMap to a file.
2. Edit the file and replace any occurence of g2_customFieldMap by g2_mapMap
3. Delete any entries not related to the map module (Entries that do NOT have GPS, Colors or ZoomLevel in the second field are not related)
4. Import the new file into the database (if the table already existed, you might get an error message)
5. Delete database cache in site admin->maintenance module
6. Done !!
- If you get an error message at step 4, open the text file and delete the entire "CREATE TABLE" statement

Upgrading from a version between v0.4.1 and v0.4.4d to 0.4.5 and up
- The route feature has been changed at version 0.4.5 to add the functionality "Create filter from route"
  - The Upgrade Path should take care of that, but if it doesn't you would see some weird behaviour on the map
  - Weird behaviour include : The map doesn't show up, the routes generate JS errors, etc ...
  - To fix the problem, go into Admin/Routes and edit your routes one by one and save them, the new format will fix the issues.
- The location for the markers has been changed to be located within the module (cleaner)
  - If your old markers do no show up the copy might have failed during upgrade
  - You can manually copy them from /pathtogallery/images/map to /pathtomodules/map/images/markers/

Personal tools