Hack 40. Plot Points on a Spinning Globe Applet

An interactive, spinning globe easily adds the "oh, wow" factor to your geocoded web pages.

Looking for a compelling way to display globally dispersed data that can be tagged with latitude and longitude coordinates, such as travel photos or events? Or perhaps you have a web form or JavaScript-enabled program that needs latitude/longitude input and you'd like to provide your users with a quick way to pinpoint the desired location.

Geosphere is an open source, versatile Java applet that does these things and more, by providing an interactive globe you can embed in your web page. The user can spin the globe, zoom in and out, and select pinpoints you have specified or input their own coordinates. If you choose to display pinpoints, they are hotlinked to URLs that will load in the browser when the user selects them. The pinpoints can be separated into groups that the user can opt to display or hide at will. Geosphere is highly customizable, so it is simple to fit it into your web site design. Best of all, if you know how to edit a web page, you know almost everything you need to know to use Geosphere.

You can download the latest version from http://hm-geosphere.sourceforge.net/. After unzipping, you will find two .jar files, GlobeApplet.jar and sjg_xml.jar. Place these in a publicly accessible directory underneath your web server's document root directory. (If you have FTP-only access to your web server, this will usually be your default home directory.) Next create an HTML page in which to embed the applet. Put the HTML file in the same directory as the .jar files.

In the HTML, add the following code:

You need Java to see Globe Applet.

Load the web page, and you should see a shiny blue marble with white coastlines on a white background. You can drag with your mouse to spin it about.

Pretty, but not interesting for very long. To make it more interesting, you can do one (or both) of two things:

• Tack some pinpoints on it that are tied to URLs.
• Use it for coordinate input: for example, to input latitude/longitude coordinates into a web form.

4.7.1. Display and Interact with Points on the Geosphere

To tack on some pinpoints, you need to define them in an XML file and then tell the applet to load them from the file.

Create an XML file in this format:

name

The XML file has following specifications:

• The tag specifies a pinpoint that may belong to a group, which is specified by a tag. The site tag is associated with its corresponding group by using the same name specified in the as the value for the attribute.
• You can have zero or more tags. If you have zero, then you can of course omit the group="" attribute in the tag.
• The attribute determines whether this group of locations is initially displayed on the globe.
• The attribute is the URL that the pinpoint is linked to. When the user double-clicks on this point, the browser will load this URL.
• The text specified between the tags is the name displayed when the user hovers the mouse pointer over the pinpoint.
• Make sure that the tag is defined all on one line (as in the following example) because sjg_xml is weird about multiline attribute lists.

Example:

amsterdam london panama city isla grande pedasi kuala lumpur singapore jerusalem tel aviv

Now place this XML file in the same directory on your server as the HTML file with the embedded applet. Add the following tag inside the section in the HTML file, where geosphere.xml is the name of your XML file:

Reload the applet page in your browser, and you should now see your points (as illustrated in Figure 4-6) and be able to double-click on them. When you double-click on a pinpoint, the associated URL loads in the browser. If you want to load the URL in a different browser window or frame, use this parameter:

Figure 4-6. Geosphere with pinpoints

You will notice that if you double-click in a region that has two or more points close together, the applet will zoom in on them. This allows you to see the distinct points more clearly and decide which one to select. You can also drag with the right mouse button to zoom. To allow the user to unzoom fully in one easy click, you need to do one of two things.

You can either display the applet's internal Unzoom button by adding this param to the applet tag in the HTML file:

which adds a not very attractive but perfectly functional Unzoom button to the applet.

Or you can use JavaScript to call the applet's zoomFullOut() method. This allows you to use a button or image of your choice on the web page, outside of the applet's area, to Unzoom, giving you better control of the look of your page. For example:

If you use the previous sample XML, when you load the applet page you'll see only London and Amsterdam pinpoints. This is because they belong to group1, which was the only group with the attribute on="true".

How do you allow the user to choose whether or not to display specific groups? Use JavaScript to call the applet's displayGroup(groupName,boolean) method. For example:

You can change many things about the applet, including most of the colors used and which features are displayed on the globe. The INSTALL.txt file in the distribution has a complete list of available parameters you can specify.

4.7.2. Use the Geosphere to Plot Your Own Coordinates

Figure 4-7 shows the geosphere centered on a custom coordinate latitude/longitude pair. There are two ways to use the geosphere to allow a user to specify coordinates.

Figure 4-7. Geosphere centered on user-defined coordinates

4.7.2.1 Add coordinates with HTML

First add this tag inside the applet tag:

This draws crosshairs in the middle of the globe and adds a "Use Target" button to the applet. When the user pushes the button, the coordinates under the crosshairs are sent to the web page's JavaScript setCoordinates() function, which must be defined in the HTML. For example:

4.7.2.2 Add coordinates with JavaScript

Next, use JavaScript to call the applet's getLatitude() and getLongitude() methods. You'll probably want to turn on the crosshair target and perhaps the coordinates display using these tags:

Example javascript:

Since you can define how to use the coordinates in JavaScript, you can do anything JavaScript allows, including using them as input to a web form, or even as input to an embedded Flash movie or another applet!