Introducing SIMILE Timeline’s documentation
A few months ago, I began to use the SIMILE Timeline JavaScript control for a project. It’s really a handy control to visually show – you guessed it – a timeline of events.
However, there’s not a lot of documentation for it. As you can see on the documentation page, in pure Open Source spirit, you will see many “for now, read the code” references for parts of the API where the documentation is the source code. There’s also a Wiki documentation page where you can find a bit more information, which is handy to find a few more things, like how to change themes.
Because of this, I though I would write a few posts with a few tips and tricks I discovered. Now, that the introduction is made, let’s start with my first post…
Why would you want to manually add events in the Timeline?
One thing you might want to do at some point, is to use Javascript to manually add events to the Timeline.
There are methods to load data in a Timeline through XML with the Timeline.loadXML method, as described in the How to Create Timelines tutorial. Also, for more efficiency over the wire, you might discover and want to use the Timeline.loadJSON method. So, why would you want to add events manually?
Well, the are many reasons why you might deem this necessary and most of these are for efficiency reasons:
- You already loaded the Timeline through XML or JSON, but you want to add new events to the Timeline without refreshing the Web page. You want to use your AJAX skills, don’t you?
- You are already using a JSON (or XML) Web service for other things on the Web page and you don’t want to make a second call to load the Timeline.
- You want to process your JSON’s Web service data to, for example, generate the HTML for the pop-up through JavaScript from the data instead of sending the whole HTML thru the wire.
How to manually add events in the Timeline?
It’s not that hard to add an event manually. When browsing the source code, you will see the definition for a new event in sources.js. The constructor is Timeline.DefaultEventSource.Event. It accepts the following parameters: start, end, latestStart, earliestEnd, instant,text, description, image, link,icon, color, textColor.
Knowing this, here’s some code to generate 50 random events up to 20 days in the past or the future. Compared to the code on the official tutorial page, the important differences are in bold.
<html>
<head>
<script src=”http://simile.mit.edu/timeline/api/timeline-api.js” type=”text/javascript”></script>
<script>
var tl;
function onLoad() {
var eventSource = new Timeline.DefaultEventSource();
//Generate 50 random events up to 20 days in the past or the future
for(var i=0;i<50;i++) {
var dateEvent = new Date();
dateEvent.setTime(dateEvent.getTime() + ((Math.floor(Math.random()*41) – 20) * 24 * 60 * 60 * 1000));
var evt = new Timeline.DefaultEventSource.Event(
dateEvent, //start
dateEvent, //end
dateEvent, //latestStart
dateEvent, //earliestEnd
true, //instant
“Event ” + i, //text
“Description for Event ” + i //description
);
eventSource.add(evt);
}
//create the timeline
var bandInfos = [
Timeline.createBandInfo({
trackGap: 0.2,
width: “70%”,
intervalUnit: Timeline.DateTime.DAY,
intervalPixels: 50,
eventSource: eventSource
}),
Timeline.createBandInfo({
showEventText: false,
trackHeight: 0.5,
trackGap: 0.2,
width: “30%”,
intervalUnit: Timeline.DateTime.MONTH,
intervalPixels: 150,
eventSource: eventSource
})
];
bandInfos[1].syncWith = 0;
bandInfos[1].highlight = true;
tl = Timeline.create(document.getElementById(“my-timeline”), bandInfos);
}
var resizeTimerID = null;
function onResize() {
if (resizeTimerID == null) {
resizeTimerID = window.setTimeout(function() {
resizeTimerID = null;
tl.layout();
}, 500);
}
}
</script>
</head>
<body onload=”onLoad();” onresize=”onResize();”>
<h1>Creating Events Manually in a SIMILE Timiline</h1>
<div id=”my-timeline” style=”height: 150px; border: 1px solid #aaa”></div>
</body>
</html>
You can see a working example here.