BasicUsage - timemap - Google Code - Basic usage for the TimeMap library.

Updated Mar 14, 2008 by nick.rabinowitz
Labels:	Featured

BasicUsage

Basic usage for the TimeMap library.

The easiest way to get the script working may be to copy code from the artist mashup. But here's a quick primer that might also help:

Make an HTML page with a <div> tag you want to hold the map, and another to hold the timeline. Give them unique ids (e.g. "map" and "timeline") and size them with CSS. I've found that the CSS can be a little easier if you put the map and timeline div tags inside container div tags that can be sized separately.

Download the timemap.js script. You may also want the images, which are just round dots color-coded to match the Google map markers in various colors. Put timemap.js somewhere on your server.

In the <head> of your HTML page, include the Google maps script, the SIMILE script, and the TimeMap script (you'll need to get an API key from Google, of course).

The page should look something like this (though of course you can put other things in here besides just the map and timeline if you want):

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Map Timeline Mashup</title>
    <script src="http://maps.google.com/maps?file=api&v=2&key=[API-KEY]" type="text/javascript"></script>
    <script src="http://simile.mit.edu/timeline/api/timeline-api.js" type="text/javascript"></script>
    <script src="timemap-1.0.js" type="text/javascript"></script>
    <link href="your-css-file.css" type="text/css" rel="stylesheet"/>
  </head>
  <body onLoad="onLoad()" onunload="GUnload();">
    <div id="timelinecontainer">
      <div id="timeline"></div>
    </div>
    <div id="mapcontainer">
      <div id="map"></div>
    </div>
  </body>
</html>

Now use an onLoad() script like the one below to set up your map and timeline.

function onLoad() {

    // Make a new TimeMap object, passing the ids of the map and timeline DOM elements.
    // This will initialize the map.
    var tm = new TimeMap(
        document.getElementById("timeline"), 
        document.getElementById("map"),
        {}
    );

    // Make a new dataset with the id "sample" and green markers.
    // You can load multiple datasets with different visual themes.
    var sample = tm.createDataset("sample", {
        title:  "Sample",
        theme:  TimeMapDataset.greenTheme()
    });

    // Create band information for the timeline as you would for any SIMILE timeline,
    // but using the eventSource from the dataset object.
    // See http://simile.mit.edu/timeline/docs/ for more info.
    var bands = [
        Timeline.createBandInfo({
            eventSource:    sample.eventSource,
            width:          "100%",
            intervalPixels: 100,
            intervalUnit:   Timeline.DateTime.DAY
        })
    ];

    // Initialize the timeline with the band info
    tm.initTimeline(bands);

    /*
     * LOAD YOUR DATA HERE
     */

} // end onLoad()

Where it says LOAD YOUR DATA HERE in the script above, you have two basic options: you can load data in JSON format, or you can load KML, which the script can parse into JSON.

To load JSON, use something like the following code:

    // Data should be an array of objects - see the code comments for format details
    sample.loadItems(items);

    // scroll to a given date - this is often necessary to make the timeline events appear
    var latestDate = sample.eventSource.getLatestDate();
    tm.timeline.getBand(0).setCenterVisibleDate(latestDate);
    // this line may be necessary if your events don't appear on the timeline
    tm.timeline.layout();

To load KML data, use a dowload-and-callback function, like this:

    // Load a KML file with TimeStamp and TimeSpan elements
    GDownloadUrl("sample.kml", function(result) {
        var data = TimeMapDataset.parseKML(result);
        sample.loadItems(data);
        tm.timeline.getBand(0).setCenterVisibleDate(sample.eventSource.getLatestDate());
        // this line may be necessary if your events don't appear on the timeline
        tm.timeline.layout();
    });

Troubleshooting

One problem I've found that can be hard to diagnose is actually the size of the divs, as set by CSS - if they are sized so that they have 0 height, for example, the javascript may throw an error. Try giving them absolute pixel sizes first, and see if you can get that working.

As noted in the code above, you may need to make the timeline scroll to a given date to make the events appear. Scrolling forces it to refresh, but the way I've written the code above it will throw an error if there are no events (or if the events haven't loaded yet). If you run into problems, try replacing the setCenterVisibleDate line with this:

tm.timeline.layout();

For example, this may be necessary if you want to scroll to the latest date, and the latest date is now - this is the default, so the timeline may not scroll anywhere in this case.

If you're loading multiple files by JSON, you may need to make sure that the last callback function makes the timeline call layout() (either explicitly or by making the timeline scroll to a date). Otherwise the events may lay out funny (overlapping) on the timeline.

Be aware that trailing commas and missing semicolons in JSON declarations can throw an error in IE. So this:

var test = {
  title: "Test title",
  description: "A description!", // <--- problem comma
} // <--- missing semicolon

needs to be this:

var test = {
  title: "Test title",
  description: "A description!"
};