Getting Started with Timeline

= Getting Started =

Here are a few easy steps to create a simple timeline. Open up your favorite text or HTML editor and start creating an HTML file.

Note
This tutorial has been partially updated for use with Timeline version 2.x. The screen shots are from Timeline version 1, so your Timeline will look somewhat different.

Examples
In addition to this tutorial, please check out:
 * The local Timeline example: a Timeline web page and data file that doesn't require a web server to use.
 * Timeline examples

Step 1. Link to the API
In your HTML code, link to Timeline's Javascript API code as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">  ...     ...    ...

Step 2. Create a DIV Element
Create a div element in your HTML code, and include a noscript element immediately after it. This page uses Javascript to show you a Timeline. Please enable Javascript in your browser to see the full page. Thank you.

You should give it an ID as well as fix its height. You can optionally set its borders, this usually makes the timeline look better.

The noscript tag will help out people who have turned off Javascript in their browser. Timeline uses Javascript, which is included in all browsers and enabled by default. It does not use Java.

Step 3. Call Timeline.create
Add two event handlers, onload and onresize, to the body element:

 ...

Then write the following code in a script block or a separate Javascript file:

Note that we put the code to construct the timeline in the onload handler to ensure that when we start to use Timeline's API, all its code has been loaded. That code creates a horizontal timeline (below) with 2 bands: in the top band, a month spans 100 pixels (approximately, since a month here refers to 30 days while not every month is exactly 30 days long); and in the bottom band, a year spans 200 pixels. The top band takes up 70% of the timeline's height, and the bottom band 30%. Note that the two bands scroll independently.



Step 4. Keep the bands in sync
To make the two bands scroll in synchrony, and then to make the bottom band highlights the visible time span of the top band, add the following code:

Gives you this...

If you try to pan one band, the other is scrolled as well.



Step 5. Add Events
To add events to the timeline, create a !DefaultEventSource as shown below. Then load the event source with data from your XML, JSON or SPARCL event file. See Event attributes and loading event files. It is not hard for developers to add additional loaders for other event file formats. Additional information on event source. Add the following code:

Gives you this...

The date field parm was added to make sure the timeline starts out showing the events immediately without requiring the user to pan first. If you do not provide a date parm, the default is now. Here is the resulting timeline with 3 events:



Take a look at example1.xml. There are 3 types of events:
 * 1) a duration
 * 2) an instantaneous event with an imprecise starting time
 * 3) an instantaneous event with a precise starting time

Click on the events to see how their bubbles are rendered based on the data in the XML file. For the exact format of such XML files, refer to the documentation on event sources. Note that loading XML files is only one way in which you can add events to timelines.

Step 6. Differentiate the two bands
Looking at the previous timeline, it is obvious that the lower band looks denser, and it will become a lot denser a lot quicker than the upper band should we add more events. Usually, a lower band usually acts as a zoomed-out overview for an upper band and it does not have to show as much detail as the upper band. Change the lower band to be an overview band:

Gives you this...

The lower band of the timeline below does not show text and its event markers are also smaller.



For more background on how a timeline is initialized including how to override defaults check out Understanding Initialization

That's it for getting started. To continue with this tutorial check out creating Hot Zones when your events get too cramped.

''If you have questions, please use the mailing list. Comments posted here are NOT read''