Add a travel to your site
Installing JourneySat on your web site is a matter of copying a few Javascript files on your site and writing the data file that contains the diary, the coordinates of the places and the URLs of the pictures.
Getting JourneySat and a Google MapsTM key
First of all you need to get a copy of JourneySat from here. Get the journeysat-1.1.1 file (either the zip or the tar.gz). If you're a developer you probably want the API documentation and the unit tests contained in journeysat-dev-1.1.1.
In any case you also need a Google MapsTM key from here. Note that if you plan to use the URL http://your.server.com/travel/mytravel.html for your travel diary you need to register a Google MapsTM key for the URL http://your.server.com/travel
Installing the files on your server
Unpack the JourneySat distribution and copy the files travel.js, resource_bundle.js and xmlparser.js to a directory of your web server. This is the directory that will contain the HTML file about your travel. It will be referenced as TRAVEL_DIR from now on.
The distribution contains also a directory called skin. Inside this directory there are the skins (i.e. the user interfaces) that you can use to customize the look and feel of your travel site. In any JourneySat distribution you should find at least the Basic and Maya skins. There are two directories with those names inside skin; the skins are in there and they are made by a few files each.
Here's how to install the Basic skin (the operations are the same for the Maya skin). Create a skin directory in your TRAVEL_DIR and copy skin/Basic from the distribution to TRAVEL_DIR/skin/Basic on the server. Don't copy the files README.txt and skin.html because they are useless on your server (but copying them will do no harm.) README.txt contains an explanation of the features of the skin and of how to integrate it into your site, so it's worth reading it.
Creating the HTML code
Copy the file skin.html from the skin/Basic directory to some other directory on your computer (not the server, not yet!). This is the template for your travel home page and you need to customize it a little.
First of all you have to specify the name of your travel at the beginning of the file, replacing the text inside the line
<title>Travel name</title>
Then you need to include your Google MapsTM key in the line
<!-- include Google Maps code --> <script src="http://maps.google.com/maps?file=api&v=1&key=your Google Maps key here" type="text/javascript"></script>
Finally rename skin.html to any other more meaningful name (it is mytravel.html in our example) and you're almost done with the configuration of JourneySat.
Creating the diary
This is the more interesting part of all the process. You have to write the travel notes, find out the coordinates (longitude and latitude) of the places you visited and include your photos. Remember that the longitude is the East-West coordinate and the latitude is the North-South one.
The starting point is this XML data file. You can make a copy of it and edit it with any text editor but now, as part of this example, copy it and mytravel.html to TRAVEL_DIR and load the URL pointing to mytravel.html into your web browser. You should see a world map centered on Africa.
It's time to start creating the travel diary. A template of the data file understood by JourneySat appears below interspaced with comments that explain how to turn it into the diary of your travel. The parts that must be changed are displayed in italics.
While you're reading the comments below you can also look at the XML data file of the demo (click here). It will be useful to compare its content to the pages of the demo.
<?xml version="1.0" ?>
<!DOCTYPE travel SYSTEM "http://journeysat.sourceforge.net/travel.dtd">
<travel>
<head>
<name><![CDATA[Travel name]]></name>
Write the name of your travel in the line above. This will appear both in the browser title bar and in large letters inside the page.
<start>
<date year="year" month="month (1-12)" day="day (1-31)"/>
</start>
<end>
<date year="year" month="month (1-12)" day="day (1-31)"/>
</end>
Write the start and end dates of your travel in the lines above, as in <date year="2005" month="7" day="9"/>. The dates will be displayed below the title.
<description><![CDATA[
Short description of the travel
]]></description>
Specify a short description of your travel. It will appear below the title.
<zoom>zoom level</zoom>
Specify the default zoom level for the satellite images. A zoom level of 4 or 5 usually is a good compromise between detail and the size of the visible area.
</head> <body>
Those two lines terminate the header of the data file and start its body. The body is a sequence of days, which in turn are a sequence of visited places. Each place can include photos.
Before any real day of travel it is good practice to show the instructions to use JourneySat and an overall map of the area you travelled accross. You can simply copy the lines below and get a starting page similar to the one of the demo. Note that this looks like a real travel day to JourneySat but the users of your site won't notice it.
<day seq="0">
<place seq="1">
<name><![CDATA[Instructions]]></name>
<coords lat="0.0" long="0.0"/>
<description><![CDATA[
<p>Use the buttons above to read the notes in the diary.<br/>
Click the icons in the map to look at the pictures.<br/>
Drag the map and use the zoom buttons to look around.<br/>
Click on the map to zoom in.
</p>
<p>The map might be unresponsive if you have a slow connection.
If you want
to hide the map for this or other reasons use the button below the map on the
right. You'll still be able to look at the picture clicking the links that
will appear at the end of the travel notes.</p>
]]></description>
<zoom>16</zoom>
</place>
</day>
You have to change two lines in the code above.
In the fourth line the tag coords contains the latitude and longitude of the center of the map. In the third line from the end the tag zoom contains its zoom level. Their values of 0.0, 0.0 and 16 yeld the world view you saw when you pointed your browser to mytravel.html on your web site.
By chosing these three values right you'll be able to prepare a nice start page for your travel. An easy way to do it is going at the beginning of the mytravel.html file and find the line //skin.showCoordinates(true);. Remove the two // characters, save the file and upload it to your server. Reload the page and click on the map. Instead of zooming in you'll get an alert box with the coordinates of the point you clicked on and the current zoom level. Use the + and - buttons above the map to control the zoom and drag the map to find the area of you travel. When you find the right viewpoint click on the center of the map and write the coordinates and the zoom level in the XML file. Remember to add again the // characters before skin.showCoordinates to restore the usual functionality of clicking on the map.
Let's start adding the first day of travel to the site:
<day seq="1">
<date year="year" month="month (1-12)" day="day (1-31)"/>
<place seq="1">
<name><![CDATA[Place name]]></name>
<coords lat="latitude" long="longitude"/>
<description><![CDATA[
]]></description>
You must type in the date you've been there, the name of the place and its coordinates. description is where your travel notes go. You can use any HTML tag in it.
Getting the coordinates of a place can require a bit of work. If you didn't have a GPS with you, you might use one of the many geocoding services around to get the coordinates of the place. A nice one that works with addresses of most of the world is Maporama. When everything else fails, you can use the map and find out the place using as references the natural or artificial landmarks that you know are close it. Click on the map after enabling skin.showCoordinates and you have the longitude and latitude.
<content>
<coords long="longitude" lat="latitude"/>
<cbody><![CDATA[
Description of the photo
]]></cbody>
<href<URL of the photo</href>
</content>
</place>
The tag content includes all the data needed to show a photo. The coordinates specify the location you've shot it and are required to put the photo icon on the map.
The tag href must contain the web address of the photo (you must load it on a web server for your friends to see it) and the tag cbody should provide a one or two lines long description of the shot.
<place seq="2">
<name><![CDATA[Place name]]></name>
<coords lat="latitude" long="longitude"/>
<description><![CDATA[
]]></description>
<content>
<coords lat="latitude" long="longitude"/>
<cbody><![CDATA[
Description of the photo
]]></cbody>
<href<URL of the photo</href>
</content>
<content>
<coords lat="latitude" long="longitude"/>
<cbody><![CDATA[
Description of the photo
]]></cbody>
<href<URL of the photo</href>
</content>
</place>
</day>
By filling out the code above with the right information you'll add to your diary a second place to the first day of travel and associate two photos to that place.
To add a second day to the diary you have to add to the file the tags <day seq="2"> </day>. Between those two tags you'll add one date tag and as many place tags as you need.
Add all the days in your travel and the places you visited and close the file with the following two lines.
</body> </travel>
Note that every day and every place must have a sequence number. Days start from 0 (the special day for the instructions) and places from 1, inside every day. Contents aren't numbered.
When the XML data file is ready load it to TRAVEL_DIR. If you changed the name of the XML file, you also need to go to at the beginning of mytravel.html and change the name of the file in the line travel.setDataFile("template.xml"); (it's about the 30th line in the file.)
Common mistakes
Be sure that mytravel.html, the XML file and the skin directory are in the same directory of the server.
If the XML file has some syntactic mistake in it the browser is likely to refuse it and JourneySat won't be able to load it. Typing in the URL of the XML file (i.e. http://your.server.com/travel/travel.xml) should make the browser show you where the error is.
Don't separate <![CDATA[ and ]]> from the tags that precede and follow them. That can give problems when loading the XML file.
The Next Step
After getting comfortable with creating a diary you can move on to the next section that will teach you how to modify and create skins, the JourneySat's user interfaces.