Web Gadget: GeoMap

Current Version

Download it now

Note that you can check the version of a web gadget by loading it directly in your browser with the "version" keyword. For example, loading "geomap.php?version" will display the current version and tell you if there is a newer version available.

Installation

You also need to place one of the map images from the end of this document into the same location as the geomap.php file.

Configuration

The configuration file is a PHP script that contains a list of values in the "CONFIG" array. It will look something like this (but normally with many more settings):

<?php $CONFIG['MapID'] = 1; $CONFIG['Levels'] = 10; ?>

Please note that this is a PHP file, and as such it must start with the <?php tag and end with the ?> tag and there must be nothing else before or after these tags and each setting must be terminated with a semicolon. String values need to be enclosed in quotes, numeric values do not need quotes. Putting any other PHP code in this file may cause the web gadget to function incorrectly.

Configuration Settings

$CONFIG['MapID']

This is a number between 0 and 255 that uniquely identifies this particular GeoMap in the database. The default is 0 and you only need to set this if you have more than one GeoMap sharing the same database.

$CONFIG['MapImage']

This is the filename of the map image to use. You can supply your own world map image (it must be exactly 1440 x 720 pixels in size, centered on 0' latitude and 0' longitude), or choose from several that are available at the end of this page.

$CONFIG['Levels']

This is a number that specifies how many different dot sizes will be used. Normally you will just leave this set to 0, which will cause the web gadget to calculate a suitable number automatically.

$CONFIG['MinSize']

This is the size of the smallest dots that will appear on the map. Anything smaller than 3 won't be very visible, and a value between 5 and 10 is recommended. The default value is 3.

$CONFIG['MaxSize']

This is the size of the largest dots that will appear on the map. A good value is between 30 and 50. There should be a big enough difference between the MinSize and MaxSize values to make them distinguishable. This value may be increased automatically by the web gadget depending on the requested detail level, so it's a rough value. The default value is 40.

$CONFIG['Color']

This is a HTML style color (eg: FFFF00 for yellow, or 00FF00 for green) for the dots on the map. Dots will also be outlined in black. The default value is 'FF0000' (red)

$CONFIG['SmallDotsOnTop']

By default, dots are sorted such that the larger dots overlap the smaller ones, which makes for a less "messy" display. If you set this value to "yes" then the dots will be sorted in reverse, causing the smaller dots to overlap the larger ones.

$CONFIG['CacheDirectory']

This is the name of a directory where the web gadget can cache data between invocations. This value must be set to a directory that exists and is writable, otherwise the web gadget will not run.

$CONFIG['MySQLHostname'], $CONFIG['MySQLUsername'], $CONFIG['MySQLPassword'], $CONFIG['MySQLDatabase']

These settings provide the hostname, username, password, and database name for a MySQL database. This database is used by this web gadget to track hits. You must create this database, but you do not need to create any tables in it as the web gadget will automatically create what it needs. It is recommended that you create one database and use it for all your web gadget configurations (as opposed to creating a new database for each web gadget).

$CONFIG['MySQLTablePrefix']

Normally this value will be left empty, but if you are using an existing database and you want to make sure that there are no table name conflicts, this value will be prepended to the name of any tables used by the web gadget.

Usage:

To record hits and increment the counter, you'll want to embed a link to this gadget on one or more web pages on your site. This is generally done through the use of an image tag like this:

<img src="geomap.php?display=invisible&count=yes">

If you prefer to actually display a map, you can use a link like this instead:

<img src="geomap.php?display=map&width=120&count=yes">

<img src="geomap.php?display=map&width=300">

Of course, you can choose to display the map without incrementing the counter by leaving off the "count=yes" bit.

You can display a particular continent by ading "area=XX" where XX is one of 'na' (North America), 'sa' (South America), 'eu' (Europe), 'af' (Africa), 'as' (Asia), or 'au' (Australia). For example, here's North America:

<img src="geomap.php?display=map&width=120&area=na">

You can also control the "clustering detail" to a degree by adding "detail=N" where N is a number from 0 to 10. The lower this number, the more distinct the hits will be, which generates more dots. As this number increases, hits that are close together geographically are merged together into a bigger dot, resulting in fewer overall dots. For example, here is a lower detail version of the image above:

<img src="geomap.php?display=map&width=120&area=na&detail=2">

Two additional optional parameters are "counter=yes" and "date="yes". If these are added, the current counter value is added to the top of the image, and the start date of the counter is added to the bottom. For example:

<img src="geomap.php?display=map&width=120&detail=2&counter=yes&date=yes">

And finally, here's some HTML you can cut and paste into your web site to display a GeoMap counter which is clickable (after installing and configuring a copy of GeoMap of course):

<a href="javascript:;" onclick="window.open( 'geomap.php', 'geomap', 'height=500,width=645,resizable' ); return false;"> <img src="geomap.php?display=map&width=120&detail=3&counter=yes&date=yes" border="0" alt="" title="Click to view my GeoMap" style="border: 1px solid #000000"></a>

If you add "count=yes" to the <img...> tag then it will also increment the counter value each time it's displayed.

Example:

To view the configuration file used in this example, click here.

Alternative Map Images:

Map #1	Map #2	Map #3	Map #4
Map #5	Map #6	Map #7	Map #8
Map #9	Map #10	Map #11	Map #12
Map #13	Map #14	Map #15	Map #16
Map #17	Map #18	Map #19	Map #20
Map #21	Map #22	Map #23	Map #24
Map #25