I volunteered at Colorado GiveCamp in April.  It’s a weekend long hackathon for a charity.  The charity I worked with, GetSmartSchools, provides classes and certifications to people who are wanting to jump into school administration.

They needed a calendar/timeline to show the commitment they are asking of people who sign up.  I’ve done something similar to this before, but it was all custom code – custom colors, text, hover text, links, etc.  At a weekend long hackathon and with a charity using a CMS for their web site, that approach wasn’t going to work.

So I did what all modern web developers do.  I looked on Google to see if someone had created a JavaScript library I could just drop in.

Introducing TimelineJS

I stumbled upon TimelineJS and thought it was so cool it would be worth talking about.  It looks like this:

You can scroll or arrow key left/right to go backwards or forwards in time.  You can zoom in or out with the plus and minus buttons.  You can host and play media in the timeline points from YouTube, Vimeo, Vine, Instagram, Flickr, SoundCloud, Twitter, Wikipedia, Google Maps, or any web page.

Quick start

The TimelineJS build page holds your hand through the process of creating a timeline.  The audience here is people who aren’t web developers, but it’s a quick way to get something working and get feedback before investing more time.

The first step is to get some data.  They walk you through using a Google Spreadsheet and give you a template with the columns you would expect: start date, end date,caption text, and columns for media, which can be a hyperlink to media content or a web page.

Once you’ve got your spreadsheet filled out, you click “Publish to the Web”.

Then you copy that URL into the TimelineJS build page as the data source for your timeline.

Next, you can set a bunch of options to make the timeline your own.  The builder has choices for size, fonts, map API keys, flipping the order so the newest stuff is the first thing you see, wrapping the embed code as a WordPress Plugin, and more.

Finally, you are given some code to embed in your blog or CMS and you even can preview how your timeline will look on your site.

<iframe src='http://embed.verite.co/timeline/?source=0Agl_Dv6iEbDadHdKcHlHcTB5bzhvbF9iTWwyMmJHdkE&font=Bevan-PotanoSans&maptype=toner&width=600&height=600' width='600' height='600' frameborder='0'></iframe>

It’s an iframe that points to http://embed.verite.co, so if that goes down, so does your timeline.  If that bugs you or you just aren’t a fan of iframes, you can go the developer route.

Developer options

If an iframe is not your style or you’ve already got a JSON data source, you can still use TimelineJS.  Here’s what the basic HTML and JavaScript might look like:

    <head>
        <!-- jQuery -->
        <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
        <!-- BEGIN TimelineJS -->
        <script type="text/javascript" src="path_to_js/storyjs-embed.js"></script>
        <script>
            $(document).ready(function() {
                createStoryJS({
                    type:       'timeline',
                    width:      '800',
                    height:     '600',
                    source:     'path_to_json/or_link_to_googlespreadsheet',
                    embed_id:   'my-timeline'
                });
            });
        </script>
        <!-- END TimelineJS -->
    </head>
    <body>  
        <div id="my-timeline"></div>
    </body>

The Source is the link to your JSON or your published Google Spreadsheet.  The Embed_Id is the ID of the element the timeline will go into in the HTML (“my-timeline” in this case).  There are more options listed on the GitHub readme.

Here’s what the sample JSON would look like (with the full model represented):

{
    "timeline":
    {
        "headline":"The Main Timeline Headline Goes here",
        "type":"default",
        "text":"<p>Intro body text goes here, some HTML is ok</p>",
        "asset": {
            "media":"http://yourdomain_or_socialmedialink_goes_here.jpg",
            "credit":"Credit Name Goes Here",
            "caption":"Caption text goes here"
        },
        "date": [
            {
                "startDate":"2011,12,10",
                "endDate":"2011,12,11",
                "headline":"Headline Goes Here",
                "text":"<p>Body text goes here, some HTML is OK</p>",
                "tag":"This is Optional",
                "classname":"optionaluniqueclassnamecanbeaddedhere",
                "asset": {
                    "media":"http://twitter.com/ArjunaSoriano/status/164181156147900416",
                    "thumbnail":"optional-32x32px.jpg",
                    "credit":"Credit Name Goes Here",
                    "caption":"Caption text goes here"
                }
            }
        ],
        "era": [
            {
                "startDate":"2011,12,10",
                "endDate":"2011,12,11",
                "headline":"Headline Goes Here",
                "text":"<p>Body text goes here, some HTML is OK</p>",
                "tag":"This is Optional"
            }

        ]
    }
}

Other details

  • It works with modern browsers and IE8 and up.
  • The TimelineJS folks say putting more than 20-30 items in your timeline will slow it down.   You don’t want to overwhelm the user with information anyway.
  • The licensing is Mozilla Public License, v2.0.
  • It’s open source and the source code is hosted on GitHub.