SIMILE Timeline: Manually Adding Events

28 Jun

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 Responses to “SIMILE Timeline: Manually Adding Events”

  1. Niek van Baalen 01. Aug, 2007 at 6:03 am #

    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. Jerome Paradis 01. Aug, 2007 at 12:11 pm #

    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 03. Aug, 2007 at 4:12 am #

    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 08. Aug, 2007 at 10:16 am #

    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. Jerome Paradis 08. Aug, 2007 at 11:32 am #

    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 10. Oct, 2007 at 12:04 am #

    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. Jerome Paradis 11. Oct, 2007 at 11:57 am #

    @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 09. Aug, 2012 at 9:47 am #

      nice mashup! and still online :-)

  8. Jörn Clausen 01. Nov, 2007 at 7:26 am #

    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. Jerome Paradis 01. Nov, 2007 at 8:56 am #

    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 20. Dec, 2007 at 6:25 am #

    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 23. Feb, 2008 at 6:01 am #

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

  12. Steve 22. Apr, 2008 at 9:44 am #

    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 30. Apr, 2008 at 8:44 am #


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

    please advise.


  14. Tim 30. May, 2008 at 10:58 am #

    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 20. Aug, 2008 at 11:06 pm #

    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. Jerome Paradis 21. Aug, 2008 at 11:59 am #

    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 17. Oct, 2008 at 2:54 pm #

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

  18. HK 23. Oct, 2008 at 11:21 am #

    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. Abhinav 06. Nov, 2008 at 6:17 am #

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

  20. Nitin 07. Nov, 2008 at 2:13 am #

    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. Jerome Paradis 07. Nov, 2008 at 9:49 am #


    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 14. Nov, 2008 at 4:54 pm #

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


  23. Rüya Tabiri 26. Nov, 2008 at 1:35 pm #

    Thank You…

  24. deam 01. Dec, 2008 at 5:15 am #

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

  25. polyboom 19. Dec, 2008 at 4:37 am #

    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. oyun 03. Jan, 2009 at 10:45 am #

    thank youu:=

  27. chat 04. Jan, 2009 at 6:49 am #

    thank you (:

  28. klamercheto 18. Jan, 2009 at 2:43 pm #

    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. sohbet odalari 07. Mar, 2009 at 3:41 am #

    thank you very much..

  30. Louis 08. Mar, 2009 at 6:36 pm #

    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 03. May, 2013 at 1:16 pm #

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

  31. Hans 11. Mar, 2009 at 9:18 am #

    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 13. Mar, 2009 at 4:07 am #


  33. shuchi 21. Mar, 2009 at 4:39 am #


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

  34. shuchi 23. Mar, 2009 at 12:01 am #

    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. Estetik 24. Mar, 2009 at 5:17 am #


  36. Yaohua Huang 02. Apr, 2009 at 12:54 am #

    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 02. Apr, 2009 at 3:20 pm #

    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. Skakunov Alex 08. Jun, 2009 at 12:19 pm #

    Thank you!

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

  39. mabra 17. Jul, 2009 at 10:15 pm #

    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 11. Aug, 2009 at 8:07 am #


    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 29. Sep, 2009 at 5:36 am #

    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. 08.06.2010 29. May, 2010 at 4:52 pm #


    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 31. May, 2010 at 3:34 pm #

      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 31. Aug, 2010 at 5:44 am #


    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 10. Oct, 2010 at 8:30 pm #

    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 20. Oct, 2010 at 3:33 pm #

      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. Jonas Hellström 14. Jan, 2011 at 11:52 am #

    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 12. Aug, 2011 at 3:03 am #


    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 03. Oct, 2011 at 12:28 am #

    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