SIMILE Timeline: Manually Adding Events

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.SIMILETimeline

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:

  1. 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?
  2. 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.
  3. 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.

    <script src=”” type=”text/javascript”></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

  //create the timeline
  var bandInfos = [
        trackGap:       0.2,
        width:          “70%”,
        intervalUnit:   Timeline.DateTime.DAY,
        intervalPixels: 50,
        eventSource: eventSource
        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;
        }, 500);
  <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>

You can see a working example here.

51 thoughts on “SIMILE Timeline: Manually Adding Events

  1. Niek van Baalen

    Hello Jerome,

    Thanks a lot for this example.
    I want to use it for showing records extracted from a mysql database.
    Instead of your dateEvent I tried dateEvent.setTime(dateEvent.getTime(1185919200));
    where 1185919200 is a value extracted fro a database.
    The dates seem not correct because they do not spread on the timeline.
    Do you know a solution?

  2. Hello Niek,

    If my memory is good, getTime() returns the current time. To set the time with a value, you would only need to call: dateEvent.setTime(1185919200);

  3. Niek van Baalen

    I finally solved the problem thanks to your help. It toke a long time to find out that there is a difference between epoch time in php/mysql and javascript. The last does it in milliseconds. So 1185919200 should be 1185919200*1000 and then it toke some time to find out that there should be ” ” around the value. So finally it is dateEvent.setTime(“1185919200000”);
    then it works.
    Thanks a lot!

  4. OOzypal

    in your code shown below the eventSource.add(evt) is executed in every iteration. is it possible to improve the code by making eventSource.add take an array?

    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

  5. The eventSource.add() method is used to add a single event.
    Obviously, we could change the above code and build a method that would accept an array of events. But then, we would still have to iterate through the array.
    Internally, the SIMILE Timeline already does such loops for the loadXML and loadJSON methods.

  6. carlos barberis

    hi there…
    i would like to add events from a mysql db, i created a php file that makes the xml format, but the API is showing an format error.
    do you know what could be the problem?

  7. @carlos barberis
    I would suggest checking your format against the sample on the SIMILE walkthrough:

    If it seems fine, some variables are required and would generate an error.

    As a last resort, you should try stepping into the SIMILE code in the loadXML method by using the Firebug plug-in for Firefox. To step into the code, you will need to change the Javascript include to add the ?debug=false parameter so that the Javascript code is not compressed.

    The SIMILE timeline is a bit touchy. If you don’t get the parameters or formats right, usually, debugging is the only to more rapidly find out what’s going on with a problem.

    • Dirk-Jan de Groot

      nice mashup! and still online 🙂

  8. Timeline has a method eventSource.addMany to add an array of events to a timeline. I don’t know if this really boosts the performance, but as it is there, why not use it?

    See my earthquake mashup at
    for reference 🙂

  9. Thanks for the tip on the addMany method.

    It was added to Timeline a few days before my post so I did not know about it.

    Good to know it’s there.

  10. sachin kambli

    hi i am creating timeline with google map your this tutorial help me a lot any suggession for creating similie timeline with google map.

    Thanks in advanced

  11. Prashant

    i want to display current date as vertical dotted line in timeline.How to do it? Please help me.

  12. Steve

    To the group,

    Does anyone know how to make different events in timeline display different colors. I want to show the events that I put in .xml file in different colors to signify different people..sorry just completed the basic tutorial and am new to this..


  13. Lawrence Ong


    Just tried the link to the example, but I’m getting a directory listing denied error…?

    please advise.


  14. Tim

    To Steve:

    If you add the following lines to the xml event tag as attributes:

    color=”red” <- change as needed (possibly can use hex)
    icon=”path to image here”

    Hope it’s not too late

  15. Andrew Finnell

    There is a problem with manually adding events. The situation you stated for wanting to add events is a similar situation I want to solve. However, this cannot be solved with the add function. The Timeline control only displays events that are added in the onLoad() function that is invoked when the page is loaded. To prove this move the code that adds the events outside of the onLoad() into a button, or timer and it will never display those events. I could not get the Timeline to dynamically update without reloading the page.

  16. Hi Andrew,

    the code here is to manually insert events on load.

    There’s a trick to add events dynamically to an existing timeline. It involves the onAddMany() method of the listener of an event source.

    After adding events to an event source, you refresh your event source with something like:

    for (var i = 0; i < eventSource._listeners.length; i++) {

    The timeline where I did such a thing heavily modified, so I’m not sure it’s the only thing needed. You might run into height distribution problems, though.

    Hope it helps.

    If it works or not, please tell me, it might make a good post in the future.

  17. Will

    Hey, i was wondering if you could modify all of the other elements of the event with this method, like color, etc?

  18. HK

    Hi, i am wondering if there is a way to disable timeline moving from right to left and left to right, in other words, only have timeline display specified timeframe only, currently you can keep on scrolling to left/right forever. Please help.

  19. The code is not working for me. It just shows the timeline without any events. Please help!

  20. Nitin

    Hello Jerome,

    I am newbie to TIMELINE,but
    Thanks for the tutorial,I got the basic example working.
    Question:How can I populate the events from the database onto the SIMILE|TIMELINE.

    any suggestion.


  21. @Nitin:

    To populate from the database, here are a few suggestions:
    – generate the Javascript from page behind code
    – load the events on the page load using Web Services or WCF.

    Hope it helps,


  22. Andrew Barker

    is there a reason you’ve closed off the example page? I’d like to take a look.


  23. Thank You…

  24. deam

    How can I change the font size of an event Tittle???

  25. polyboom

    Hello Jerome,

    good to see a living simile-blog. I hope we can collect some informations about this nice timeline in here. (o:
    Maybe someone can help me with my problem/question:
    I want to display a lot of historical events with a automatically generated XML-Document. Unfortunately i have no influence over the syntax of the generated XML-Doc. How can i still use these files for my timeline? Thx for reading and i hope this project continues with growing.

  26. thank youu:=

  27. thank you (:

  28. klamercheto

    I’m trying to load the xml data from JSP. The data is generated with struts. The problems is: I’m becoming an Internal Server Error 🙁 Is there anybody who could help me…

    Thanks in advance.

  29. thank you very much..

  30. This method stopped working for me with Simile 2.3.0 (released March 5th, 2009), after painstaking trial and error I found out that they changed the API to create Events. It now takes 1 argument, a JSON object. See sources.js line 320 for the valid variable names.

    var evt = new Timeline.DefaultEventSource.Event(
    ‘start’:dateEvent, //start
    ‘end’:dateEvent, //end
    ‘latestStart’:dateEvent, //latestStart
    ‘earliestEnd’:dateEvent, //earliestEnd
    ‘instant’:true, //instant
    ‘text’:”Event ” + i, //text
    ‘description’:”Description for Event ” + i //description

    • Brian Houle

      Thanks for the tip. You just save me hours of work!

  31. Hans

    After implementing Louis solution I ran into the folowing problem while clicking on an event: in simile-ajax-bundle.js a call to function getDate() is not possible (…return new Date(A.getDate()+B.. ).
    A is already a millisecond value so “.getDate()” could be removed and it worked again.

  32. chat

  33. shuchi


    I used the same code but I am not getting events It just shows time line.Is any one help me.

  34. shuchi

    As i am using timeline 2.3.0 but if i am using link that is in your example then its working.Could you me why its not working with 2.3.0.

  35. THANKS

  36. Yaohua Huang

    Need to change event construction into:
    [A new member “id” is needed]

    var evt = new Timeline.DefaultEventSource.Event({
    start:dateEvent, //start
    end:dateEvent, //end
    latestStart:dateEvent, //latestStart
    earliestEnd:dateEvent, //earliestEnd
    instant:true, //instant
    text:”Event XXX”, //text
    description:”Description for Event XXX” //description

  37. Patrick Finnicum

    does anyone know what may be going on here? everything works exceptionally well for me, EXCEPT the event color.

    icon works, and text color works, but not the event color. i’ve tried “red” and “#FF0000”, but still isn’t going.

    Thanks to anyone who may help.

  38. Thank you!

    What I am interested in is how to change an event start date by dragging it horizontally…

  39. mabra

    Hi !

    Exactly, what I searched for and looks nice. But sad to say:I can not make of the variants running, the added event [I used only one] is not displayed.

    More strange:Even the page is not working, if I use local references to the 2.3.0 version;I am sure, I miss something [nothing for 2.3.0 in docs!].

    Any help would really be great!


  40. Miguel Duran


    Is there a way to load info on Timeline from a Mysql db via php without generating an XML or Json structure ? I’m new to Timeline and relatively new to php so I’d appreciate a code snippet or some guidance. Thanks !


  41. Talhah

    Hi Guys

    I am able to create a custom XML event file on the fly. the only issue i am having is reloading the new xml file dynamically without having to refresh the page.

    Anyone have experience with this?


  42. Hello,

    Is there a way to load info on Timeline from a Mysql db via php without generating an XML or Json structure ? I’m new to Timeline and relatively new to php so I’d appreciate a code snippet or some guidance. Thanks !


    • Jerome Paradis

      Well, since SIMILE is in Javascript, you need to supply it with data it can read. This means XML or Javascript. However, you don’t have to embed it in your page. You could write some AJAX jQuery code and use Web services or an API to supply the code with data.

  43. Patricia


    I’m trying to do a timeline but I’m having a problem loading the XML file. I following the tutorial but when I load their example I get this error: Failed to load data xml from test.xml
    I would like to known if anyone know why (both files are in the same folder).
    I want to load data from django models, I was wondering which is the best way to load that kind of data.
    Thanks for any help, I appreciate!

  44. Bob T

    Jerome – excellent writeup – thanks! Have you stumbled across a way to insert a search field for events? I’m still….searching…and hoping…created a local version with hundreds of events and thought this ability would be very helpful. Thanks again.

    • Jerome Paradis

      Hey Bob,

      I’ve used two methods to do this:
      1) use AJAX and do the search on the server followed by some Javascript filtering
      2) do the search directly in Javascript by looping through the events and applying regex searches on the appropriate fields

  45. I’m going out on a whim here to see if you can help me out with some insight into this minor issue I got.
    Is there any way that I can make timeline tapes of my choice to get drawn from the start date to today’s date?
    I’m using XML as the source since I find it to be comfortable and quick to edit. But I can’t find any property that corresponds to the behaviour I’m looking for.

  46. palak agarwal


    i want to change the interval unit of timeline to 4 weeks on upper band and 2 months on lower band. Kindly help me out …. if anybody has solution to this problem please mail me .

  47. Parth

    thanks for your good guidelines for Timeline.
    In timeline if we click on any event, then I want to diplay pure html content in the pop-up menu.
    The html data might be coming from some other file.
    Can you give me some idea about it. ?
    I am stuck with this problem.
    thanks in advance.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>