The Tinderbox Timeline Library

The Tinderbox Timeline Library is a Javascript library that renders timelines in an HTML canvas element. It is primarily intended to support export from Tinderbox timelines to the Web, which often requires nothing more than pressing the EMBED… button in Timeline View and pasting the generated code into your Web page.

This document describes a variety of options that Javascript developers may use to customize the appearance and behavior of Tinderbox Timelines. Most Tinderbox users will not need to do this.

Requirements

The Tinderbox Timeline Library works in most modern browsers that support the <canvas> tag.

A bug in iOS 3.1 causes some rendering problems on the Apple iPad. iOS 4 corrects this issue for the iPhone and is expected to fix it on the iPad as well.

The Tinderbox Timeline Library depends on the following libraries:

prototype.js
scriptaculous

The Javascript code generated by Tinderbox Timeline view loads these libraries from the Google repository. If you have several timelines on your page, only the first one needs to load these libraries.

If you don’t plan to use the tip feature to add information to events, you may omit the scriptaculous library.

How It Works

The Tinderbox Timeline Library is designed for quick and easy rendering of timelines without requiring Javascript programming or the construction of auxiliary data files.

A timeline includes

a <canvas> tag, which must have a unique ID so the timeline library knows where to draw the timeline
a brief Javascript snippet that creates a Timeline object (which describes the timeline), adds data about the events in the timeline to that object’s data field, and then calls Timeline.register() to initialize the timeline.

For example:

var theTimeline_timeline=Timeline.create( {element:"timeline"} );

theTimeline_timeline.withEvents( [

{start:"15 Jun 1783", end:"15 Jun 1801", band:1, y:0.3, label:"Pitt the Younger "},

{start:"15 Jun 1793", band:0, y:0.8, label:"Cotton gin"}]));

</script>

The Timeline Object

The Javascript Timeline object manages timelines. It has two public functions.

Timeline.create( {element: id, ...options} )

Creates a new timeline object and associates it with a specific <canvas on the page.

Timeline.withEvents( [ {...event...}, {... event...} ]

Adds events to the timeline, and draws the timeline on the canvas while arranging appropriate callbacks for handling mouse events in the canvas.

Timeline Options

Timeline.create() builds a new timeline object. You then events to the timeline and call Timeline.register() to set up callbacks that draw the timeline and handle mouse events inside the timeline canvas.

Timeline.create() has one required option and many additional options which you can use to change the appearance of the timeline.

Required Parameters

element: [string]: The HTML id of the canvas in which this timeline should be drawn.

Other Parameters

bands: [array of strings]: An array of strings that will be used as labels for horizontal timeline bands
bandHeights: [array of numbers]: An array of the bottom position of each timeline band. For example, bandHeights[100,250] would request that the top band be 100 pixels in height, while the second band would be 150px in height.
backgroundColor: [string]: Sets the background color of the timeline. For example, background-color: rgb(255,255,255) would set the background to white.
bandColor: [string]: Sets the color used to tint alternate bands in the timeline. For example, bandColor: rgba(0,255,128, 0.10) would color alternate bands with a tint of blue-green with opacity of 10%.
bandLabelColor: [string]: Sets the color used to draw the band labels. If not specified, band labels are drawn in very light gray, "rgba(0,0,0,0.1)".
bandLabelFont: [string]: The font used to draw band labels. This may be a list of font names, separated by commas. Font family names like "serif" or "sans-serif" may also be used. For example, '"Hoefler Text",Georgia,serif'.
frameColor: [string]: The color used to frame the timeline.
labelColor: [string]: The color used to draw text labels of events. May be overridden by individual events.
linkColor: [string]: The color used to draw text labels of events that have URLs, and which may be clicked on. May be overridden by individual events.
labelFont: [string]: A font name, or list of font names separated by commas. Font names that contain spaces should be enclosed in quotes. Font families (e.g. "serif", "sans-serif") may also be used. The font used will be the first font in the list that is available on the destination system.
labelSize: [number]: The size, in pixels, used for drawing event labels and the timeline scale
markerColor: [string]: The color used for drawing timeline markers. Individual events may each override this color.
scaleColor: [string]: The color used to draw the background of the time scale at the base of the timeline.
scaleHeight: [number]: The height, in pixels, of the timeline scale drawn at the bottom of the canvas.
stamp: [string]: A stamp or watermark may be drawn diagonally over the timeline to indicate that the timeline is preliminary, a draft, or a sample.
stampColor: [string]: The color used for drawing the stamp. Typically a translucent color is used, such as "rgba(0,0,0,0.2)".

Describing Events

theTimeline.withEvents( [ {event 1}, {event 2} ]) receives an array of elements that describe events to be shown in the timeline. For example:

theTimeline.withEvents( [

{start:"Jun 15, 1783", end:"Jun 15, 1801", band:1, y:0.3, label:"Pitt the Younger "},

{start:"Jun 15, 1793", band:0, y:0.8, label:"Cotton gin"}]));

Required Parameters

start: (date): The start date of the event. Any date string acceptable to JavaScript may be supplied; RFC 1123 dates are recommended.
label: (string): The textual label used to identify the event

Optional Parameters

band: (number): The horizontal band in which the event should be placed. The topmost band is band 0. If no band is specified, band 0 is assumed.
end: (date): The end date of the event. If no date is supplied, only the event's start is shown.
labelColor: (color): The color used for drawing the event’s text label. If no color is specified, the event is drawn in black.
linkColor: (color): The color used for drawing the text label of events that have a URL. If no color is specified, the text is drawn in blue.
marker: (bool): If true, a vertical bar is drawn from the event to the timeline scale at the base of the timeline. If absent or false, no marker is drawn.
markerColor: (color): The color used for drawing the event’s marker – a vertical bar drawn from the event to the timeline scale at the base of the timeline. If marker is false, markerColor has no effect.
tip: (string): A string, or HTML fragment, which will be displayed when the mouse hovers over the event. If no tip is supplied, hovering over the event has no special effect.
URL: (string): A fully-qualified URL (e.g. “http://www.eastgate.com/”). If supplied, the event text is drawn in linkColor and, when the event is clicked, the designated URL will be opened in the browser.
y: (number, ranging from 0 to 1.0): The relative vertical position of the event within its band, where 0.0 represents the top of the band and 1.0 represents its bottom. Tinderbox provides estimated placement based on its own presentation, but adjusting the exported y value may sometimes improve layout or avoid unwanted event overlap.

Timeline Resources

The Tinderbox Timeline Library provides a fast and simple way to share Tinderbox timeline data on the Web. Several other systems provide useful tools for working with timelines; thanks to Tinderbox’s flexible export tools, these systems are not very difficult to use with Tinderbox and might provide a useful alternative.