File Release Notes and Changelog
Notes:
-------------------------------------------------------------------------------
See BUILD.txt for build instructions, which explains how/where to obtain
GlobeApplet.jar and sjg_xml.jar. If you obtained this in a pre-built
distribution the jar files should be included in the zip file.
To install and use GlobeApplet.jar, put it on your web server along with
sjg_xml.jar. 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 put a variation of the following html code:
<applet name="Globe"
codebase="."
archive="GlobeApplet.jar,sjg_xml.jar"
code="org.akuaku.geosphere.globe.GlobeApplet.class"
width=200 height=300 MAYSCRIPT>
<param name=size value="200">
<param name="bgcolor" value="FFFFFF">
You need Java to see Globe Applet.
</applet><br>
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 long. To make it more interesting you can
do one (or both) of two things:
1) Tack some pinpoints on it that are tied to URLs.
2) Use it for coordinate input via javascript calls, for example to input
Latitude/Longitude coordinates into a web form.
--------------------------------------------------------------------------
DISPLAYING AND INTERACTING 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:
<geosphere>
<group name="" title="" color="" on=""/>
<site group="" latitude="" longitude="" href="">name</site>
</geosphere>
Where:
- The <group> name attribute is the name used in <site group="">
- You can have zero or more <group>'s. If you have zero then you can of course
omit the group="" attribute in the <site> tag.
- The <group> on attribute determines whether this group of locations are
initially displayed on the globe,
- The <site> href 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 <site></site> tags is the name displayed when
the user hovers the mouse pointer of the pinpoint.
- Make sure that the <site> tag is defined all on one line (like in the
example below) because sjg_xml is weird about multiline attribute lists.
Example:
<geosphere>
<group name="group1" title="first group" color="ff0000" on="true"/>
<group name="group2" title="second group" color="00ff00" on="false"/>
<group name="group3" title="third group" color="00ffff" on="false"/>
<site group="group1" latitude="52.22" longitude="4.53" href="http://mysite.com/amsterdam/">amsterdam</site>
<site group="group1" latitude="51.32" longitude="0.5" href="http://mysite.com/london/">london</site>
<site group="group2" latitude="8.58" longitude="-79.32" href="http://mysite.com/panama/">panama city</site>
<site group="group2" latitude="9.4833" longitude="-82.6667" href="http://mysite.com/panama/">isla grande</site>
<site group="group2" latitude="7.5333" longitude="-80.0333" href="http://mysite.com/panama/">pedasi</site>
<site group="group3" latitude="3.08" longitude="101.42" href="http://mysite.com/malaysia/">kuala lumpur</site>
<site group="group3" latitude="1.18" longitude="103.50" href="http://mysite.com/singapore/">singapore</site>
<site group="group3" latitude="31.47" longitude="35.13" href="http://mysite.com/palestine/">jerusalem</site>
<site group="group3" latitude="32.0667" longitude="34.7667" href="http://mysite.com/palestine/">tel aviv</site>
</geosphere>
Now place this XML file in the same directory as the your HTML file on your
server. Add the following tag to the <applet></applet> params in the HTML
file, assuming you named the XML file geosphere.xml:
<param name=coordinatesXML value=geosphere.xml>
Reload the applet page in your browser and you should now see your points and
be able to double click on them.
You will notice if you double click in a region that has two or more points
close together that the applet will zoom in on them. This is to allow them to
separate so you can more clearly decide which point to select. To allow the
user to unzoom from this point you need to do one of two things:
1) display the applet's internal unzoom button by adding this param to the
applet tag in the HTML file:
<param name="showzoomoutbutton" value="true">
which adds a not very attractive but perfectly functional 'Unzoom' button
to the applet.
2) Use javascript to call the applet's zoomFullOut() method. This allows you
to use a button or image on the web page outside of the applet's area. This
gives you better control of the look of your page. For example:
<input type="button" value="Unzoom" onClick="document.Globe.zoomFullOut()"/>
or
<img src="unzoom.gif" onClick="document.Globe.zoomFullOut()"/>
If you used the example XML above, when you load the applet page you'll see
only London and Amsterdam pinpointed. This is because they belong to group1
which was the only group with on="true". If you're using groups how do you
allow the user to choose whether or not to display them? Use javascript to
call the applet's displayGroup() method. For example:
<form name="groupdisplay">
Display Group 1:
<input type="checkbox" name="group1" CHECKED
onClick="document.Globe.displayGroup('group1',document.groupdisplay.group1.checked)"/><br/>
Display Group 2:
<input type="checkbox" name="group2"
onClick="document.Globe.displayGroup('group2',document.groupdisplay.group2.checked)"/><br/>
Display Group 3:
<input type="checkbox" name="group3"
onClick="document.Globe.displayGroup('group3',document.groupdisplay.group3.checked)"/><br/>
</form>
You can change many things about the applet, including most of the colors used
and which features are displayed on the globe. Explore the full applet
parameter list after the next section to learn more.
--------------------------------------------------------------------------
USING THE GEOSPHERE FOR COORDINATE INPUT
--------------------------------------------------------------------------
There are two ways to use the geosphere to allow a user to specify coordinates.
1) First add this param to the applet tag:
<param name="showinputbutton" value="true">
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 javascript setCoordinates() function
which must be defined in the HTML, for example:
<SCRIPT>
function setCoordinates(lat, lon) {
alert('lat='+lat+' and lon='+lon);
}
</SCRIPT>
2) Use javascript to call the applet's getLatitidue() and getLongitude()
methods. You'll probably want to turn on the crosshair target and perhaps
the coordinates display using these params:
<param name="showtarget" value="true">
<param name="showcoords" value="true">
Example javascript:
<SCRIPT>
function displayCoordinates() {
lat = document.Globe.getLatitude();
lon = document.Globe.getLongitude();
alert('lat='+lat+' and lon='+lon);
}
</SCRIPT>
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!
--------------------------------------------------------------------------
APPLET PARAMETERS
--------------------------------------------------------------------------
The following parameters are recognized by the applet. Also listed are their
default values if not specified. The parameters are case-sensitive:
<param name="coordinatesXML" value="mypoints.xml">
The coordinate XML file. This must be defined for the applet
to display any points. In development this file has been stored
in the same directory as the applet codebase. Example XML file:
<geosphere>
<group name="group1" title="first group" color="ff0000" on="true"/>
<group name="group2" title="second group" color="00ff00" on="false"/>
<group name="group3" title="third group" color="00ffff" on="false"/>
<site group="group1" latitude="52.22" longitude="4.53" href="http://mysite.com/amsterdam/">amsterdam</site>
<site group="group1" latitude="51.32" longitude="0.5" href="http://mysite.com/london/">london</site>
<site group="group2" latitude="8.58" longitude="-79.32" href="http://mysite.com/panama/">panama city</site>
<site group="group2" latitude="9.4833" longitude="-82.6667" href="http://mysite.com/panama/">isla grande</site>
<site group="group2" latitude="7.5333" longitude="-80.0333" href="http://mysite.com/panama/">pedasi</site>
<site group="group3" latitude="3.08" longitude="101.42" href="http://mysite.com/malaysia/">kuala lumpur</site>
<site group="group3" latitude="1.18" longitude="103.50" href="http://mysite.com/singapore/">singapore</site>
<site group="group3" latitude="31.47" longitude="35.13" href="http://mysite.com/palestine/">jerusalem</site>
<site group="group3" latitude="32.0667" longitude="34.7667" href="http://mysite.com/palestine/">tel aviv</site>
</geosphere>
<param name="browsertarget" value="newPopup">
The browser window the applet uses to load URL. Default is same window.
<param name="bgcolor" value="FFFFFF">
The background color. Default is black.
<param name="pincolor" value="00FF00">
The color of the non-grouped pinpoints. Default is red.
<param name="globecolor" value="9999FF">
The color of the sphere. Default is blue.
<param name="coordscolor" value="FF0000">
The color of the coordinates (if displayed). Default is yellow.
<param name="targetcolor" value="FFFFFF">
The color of the crosshair target (if displayed). Default is yellow.
<param name="coastcolor" value="101010">
The color of the coastlines. Default is white.
<param name="showcoords" value="true">
Show the coordinates at upper left corner. Default is false.
<param name="showinputbutton" value="true">
Show the "Use Target" button. Default is false.
If true, the crosshair target is displayed and the "Use Target" button
is added to the applet. When the user pushes the button, the lat/long
coordinates at the current target point are used in an invocation of
the javascript method setCoordinates(lat,lon) which must be defined
in the web page in which the applet is emedded.
Example HTML:
<SCRIPT LANGUAGE="Javascript">
function setCoordinates(lat, lon) {
alert(lat);
}
</SCRIPT>
<param name="showtarget" value="true">
Show the crosshair target. Default is false, although if certain
other options are true, this is automatically true.
<param name="initialLatitude" value="41.15960">
The initial orientation of the globe. Default is Black Rock City.
<param name="initialLongtitude" value="-119.63284">
The initial orientation of the globe. Default is Black Rock City.
<param name="zoom" value="scroll">
<param name="zoom" value="mouse">
<param name="zoom" value="none">
The scroll method to use. The mouse method allows the user to zoom
via right mouse button click and drag. The scroll method provides
a scroll bar to adjust the zoom level. The mouse method has been known
to crash M$ Internet Explorer on Windows XP, I suggest using 'scroll' or
'none'. If you use 'none' be sure to provide an unzoom button for the
user.
<param name="showzoomoutbutton" value="true">
Show the Unzoom button which resets the globe zoom level to display the
full sphere. Default is false.
<param name="externalURL" value="http://www.mapquest.com/maps/map.adp?latlongtype=decimal&latitude=HEADMAP_LAT&longitude=HEADMAP_LON&zoom=12&size=big">
There is no default for this. This is an experimental parameter at
the moment. The value must contain a URL with HEADMAP_LAT and HEADMAP_LON
in them. Including an externalURL value tells the applet to get
the latitude/longitude of the mouse click and pass it to this URL,
replacing HEADMAP_LAT and HEADMAP_LON as appropriate. Right now if
you have points defined on the globe, then the nearest point is used
rather than exactly where the mouse is clicked, and the SHIFT key
must be held down (otherwise it just goes to the point's href defined
in the XML as usual). If you have no points defined on the globe, you
don't need to use the SHIFT key and it uses the exact mouse coordinates.
<param name="framemode" value="true">
This is used in conjunction with the externalURL parameter above.
The default is false. If set to true then the double clicking on a
pin point will cause the browser to load -both- the associated URL
from the XML file and the externalURL specified in the externalURL
parameter. These are loaded in a horizontally split frame set.
<param name="frametopsize" value="60%">
Used in conjunction with the framemode parameter above. Default is 50%.
<param name="maxTitles" value="6">
How many titles to display in the lower left corner when hovering over a
set of points. The dfault it 4.
<param name="pinlength" value="15">
How long the pins should be. Default is ten. "Ten what" you ask? Hard to
explain, just experiment until you're happy.
<param name="showzoomoutbutton" value="true">
-------------------------------------------------------------------------------
Changes:
