Friday, February 28, 2014

Adding Search and navigation by year to TimelineJS

TimelineJS is easily the coolest timeline on the planet. It has a wonderful slider and excellent animations and design. But, and this is a big but, it lacks a proper API for programmers. Making it do anything except the original uses envisaged by its designer is a pain. For example, I wanted to search the timeline. We use it for a timeline of poems, initially 720, but later this will grow to 2,200. And without search you can't find when he wrote what. Nobody is going to flick through that many entries. (And yes it does work well with 720 entries - the only problem is the time it takes to download, not render, since we don't use video or even graphics much). So I wanted to add a search. It turns out that the only practical way to do this that I could find was to add a function to the timeline.js code itself. So I added a search button, and bound my function to it:

function buildNavigation() {
    VMM.bindEvent("#search_button", doTimelineSearch);
    VMM.bindEvent("#year_dropdown", goToYear);

I also have a text box called "search_expr" to hold the search text and error messages. First I tried searching the HTML itself using jQuery but the browser caches most of the elements, so I had to use the copy of the original JSON object that TimelineJS uses to construct the slides. It was still hanging around in config.source. I added some code to the NAVIGATION section of timeline.js:

First I search from the current slide+1 to the end, then from the start to the current slide. If it is only on the current slide or not found, I write "not found" in the search box. Pretty simple. No doubt it could be written more elegantly but it was easier to debug like this, and I'm not very good at Javascript. But, hey, it works. Here it is, live. And yes it requires jQuery.

After thinking about it for a bit I added a goToYear function, which allows the user to quickly jump to an interesting section of the timeline.


  1. not seem to work when i integrate your code the timeline stop displaying

  2. You need to add HTML elements to provide the search expression and year inputs. See In the code above " $("#search_expr").val();" obviously requires there to exist on the page an input element with the ID set to "search_expr". And for the year dropdown I used a select dropdown with id=year_dropdown. Also if you do not initialise the timeline with JSON you may have to customise the search, given that the above code relies on the existence of config.source.

  3. the code seems to be broken. i'm attempting to fix it but copy-paste work tends to go south. (there's an extra brace at towards the end, it seems).

    the proof of concept example no longer works, have you done anything with the code base since?

    1. Hi Bassel,
      it is dangerous to modify shared code because when it gets updated your modifications are of course embedded in the old version. But I don't have time to fix this, so I just pasted my working copy of timeline.js with the search function. But please note the previous comment: you have to embed an element to hold the search expression. You can see it working on . Look for something like "Charles Chidley".