Tool Name: TimelineJS

Version Number/Release Date: unknown

Developer Website: http://timeline.knightlab.com

Reviewed by: Susanna Coleman

Review Date: February 8, 2015

Tags or Keywords: timeline, events, chronology, chronological, history, visualization, json, knightlab, timelinejs, verite

General Purpose of Tool: TimelineJS allows users to create customized, interactive timelines of chronological events. Users can include images, video, Wikipedia entries, and other multi-modal content with the text of their timelines, and the resulting widget can be placed into HTML files, including WordPress pages. TimelineJS’s developers intended it for a range of users, from novices who can create timelines using a Google spreadsheet to experts who can use JSON (JavaScript Object Notation) to build more customized timelines.

Review: As a novice to timelines and databases (but not to spreadsheets and general web development), I reviewed TimelineJS’s simplest functions: drawing information from a Google Sheets spreadsheet to build a timeline in an iframe, which could be pasted into the HTML code of a web page. Due to my lack of expertise, I was unable to test TimelineJS with a more complex database read using JSON.

Ultimately, TimelineJS did perform its intended function: it helped me create a visual timeline with embedded media, using a Google Sheets spreadsheet to feed in data. The timeline displayed well on both my computer and my mobile phone, although TimelineJS is intended mostly for computer use and is not available as a mobile app. I did not need to create an account or download software; the only requirement for novice use was a Google account to host the spreadsheet from which my timeline drew its data. The TimelineJS website itself generated my timeline after I added data to my spreadsheet, and the only data storage necessary was for the spreadsheet itself, kept in my Google Drive in the cloud. (I did choose to include an image from my hard drive on my timeline, which required additional cloud storage on Tinypic, but a user could conceivably include only images hosted on other websites. The drawback to that method would be a broken image if the host was no longer available.) Other benefits of TimelineJS include its being free and its support for over forty languages, with the ability for users to add translation files for additional languages. All in all, once my timeline was created, it worked well, and I intend to keep using TimelineJS to add to it.

Unfortunately, however, TimelineJS did not perform well during the timeline creation process, and it lacked sufficient documentation to help truly novice users past the problems which occurred. TimelineJS’s web site includes only an FAQ for help; it recommends a user turn to its community support forum or an older, archived forum for answers not found in the FAQ. The support forum often did not have help for the issues I encountered, and I did not have time to post my questions and wait for a reply; instead, I resorted to trial and error to solve my problems myself. The TimelineJS tutorial video was only two and a half minutes long, with the first minute devoted to advertising the tool. The last minute and a half offered a general tutorial but little help for the issues I encountered. While the template spreadsheet provided did include tooltips, they often contained no more information than whether a field was required or optional. My impression was that TimelineJS’s creators view the tool as so intuitive, users will not need much help, which sadly is not the case. This lack of support would be a major impediment for a user completely unfamiliar with spreadsheets in general, Google Sheets in particular, or general web development.

Building my timeline took approximately three hours, much longer than I expected since I was familiar with web development. Many of the problems I encountered while building my timeline were related to Google Sheets, particularly because TimelineJS’s template did not work with the current version of Sheets. My issues and work-arounds were as follows:

  • Google Sheets error message that a valid URL was invalid: I removed an URL in the template and replaced it with an URL for my content. This seemed to change the URL’s cell to plain text format rather than a hyperlink, and in the old version of Google Sheets, I was unable to create a new link. After discovering this fact via Google’s help system, I converted my spreadsheet to the new Sheets format, which led to the next issue.
  • TimelineJS not compatible with current Google Sheets files: My timeline simply would not load with my spreadsheet; I received a message that said “still waiting on Google Docs, trying again.” After attempting several other work-arounds, I realized the problem could stem from my upgrade to the new format. I cut and pasted the material from my spreadsheet back into the original template, in the old Google Sheets format. This file in the older format worked and produced a timeline.
  • Google Sites not supported: My timeline would not display on a page in Google Sites. The community support forum suggested this was a common issue, and while there was an unofficial workaround, it did not always succeed, and I did not have the time to test it.
  • Wikimedia Commons pages not supported: Although TimelineJS supports importation of Wikipedia entries, it displays broken images for pages on Wikimedia Commons. I had to link directly to the Wikimedia Commons image file itself.
  • Other minor issues: lack of detailed instructions left me to guess at what to do for several steps; cursor turned to a crossed out circle over the textbox containing generated code to cut and paste, suggesting an error when there was none; the font preview did not list all available fonts; Google Maps would not display if linked using Google’s short URL; changing settings in the code generator did not always update the code, requiring a hard refresh; timeline did not resize vertically if the size option was altered, leading to scrollbars when the height was set below 650 pixels.

I do feel that TimelineJS is useful for Digital Humanities projects requiring timelines, as well as any other user who wishes to display chronological information along with media. However, I have the following recommendations to make the tool usable for novices:

  • More detailed instructions, tutorials, and help files
  • Support for current Google Sheets files (or at least a warning that they are not compatible with Timeline JS)
  • Support for Google Sites or instructions for a reliable workaround
  • Support for linking to Wikimedia Commons pages

My test timeline and a detailed record of the steps I took to build it are included below.

Ease of Use: TimelineJS’s developers intend it for use by the general public, with options for beginners (building from a Google spreadsheet) to experts (building from a database with JSON). Despite these intentions, TimelineJS is not suitable for a beginner with little to no experience in either Google Sheets or web development. Set up of TimelineJS requires the ability to troubleshoot errors in both Google Sheets and iframes HTML.

Cost: Free (licensed under Mozilla Public License version 2.0).

Requirements: Web-based requiring a “modern browser” or Internet Explorer 8 or above; cannot run in IE7 compatibility mode. Draws data from Google Sheets (relying on Google’s API) or from a database through the use of JSON. Tested on Windows 7 PC with Mozilla Firefox 35.0.1 and Internet Explorer 11; Android mobile phone using Firefox and default browser app.

Rival or Comparable Tools:

  • Aeon Timeline by ScribbleCode
    • Pros: better depiction of relationships between events, more flexibility in calendar display, editing within the timeline itself, more support
    • Cons: cost ($40)
  • TimeRime by Hoppinger
    • Pros: file storage, optional paid version with more features
    • Cons: poorer timeline design with no control over design for free version, limited number of events per timeline even with paid version, very little support

Other Reviews:

Test Timeline:

Source for Test Timeline:

  • Updegraph, Jr., Charles L.  Official Marine Corps Units of World War II.  Washington, D.C.: History and Museums Division Headquarters, U.S. Marine Corps, 1972.  Print.
    (also available online)

Additional Links:

Steps to Build Test Timeline:

  1. The first step listed on TimelineJS’s website was to open the spreadsheet template from a provided link. Clicking “Use this template button” copied the template to my Google drive. I renamed the spreadsheet.
  2. The TimelineJS site provides very little help in filling in the spreadsheet: “Drop dates, text and links to media into the appropriate columns. Note: Don’t change the column headers, don’t remove any columns, and don’t leave any blank rows in your spreadsheet.” The next step given is to publish the completed spreadsheet to the web, so I felt like I was on my own in adding data. TimelineJS provided a link to a tutorial video on YouTube, which I watched although I prefer to follow textual instructions due to my learning style and the fact that I have limited bandwidth from my ISP. The first minute of the 2:30-long video only promoted the tool without offering any tutorial. The remainder of the video did offer a generalized tutorial providing slightly more information than the written instructions, but I was still left with the impression that the tool’s authors view it as so intuitive, users will not need much help.
    Note: I did find a user-made walk-through video that provides more detail than the official tutorial video. However, I did not watch the walk-through before testing the tool as I wanted to rely only on what information the developers provided.
  3. The template did include tool tips for what information went in the various columns, but they were not always helpful. For instance, the tool tip for the “Start Date” column simply read “Required,” with no information on what exactly “Start Date” meant or how to format the date. The next column, “End Date,” was labeled as “Optional” with no other information. I decided that the dates would allow me to create either an event that lasted a period of time (like World War II) or an event that only occurred once (like the opening of a barrage balloon training school). I began testing the tool by altering the information in the template to include barrage balloon-related events. Having a basic knowledge of Microsoft Excel and Google Sheets, I did not encounter difficulty in filling in the dates and text. None of the first four columns had tool tip instructions other than to indicate what material was required or optional, but the “Media” column noted what kinds of media could be linked into the timeline. I entered a range of available media to test how each would display. I ran into trouble with my first link, to the Wikipedia entry on barrage balloons. Although the tool tip stated media could include Wikipedia, the spreadsheet alerted me that the URL was not valid. I returned to TimelineJS’s web page for help. I found none on the page, so I turned to the “community support forum” and did a search for “Wikipedia,” which yielded no results. I tried a link to an image and still got the invalid URL warning. Next, I tried pasting the link IURL in the data entry field at the top of the spreadsheet, rather than directly into the cell. I did not get the warning, but the link did not hotlink and turn blue like the links in the template. Unsure if the media would work in the timeline or not, I moved on.  I appreciated the next column, “Media Credit,” for encouraging users to cite their sources. I was unclear about the purpose of the optional “Media Thumbnail” column, which required a link to an image only 32×32 pixels, as it seems like a very small thumbnail for a visually rich timeline. The “Type” column, used to indicate the title slide, was explained well in its tool tip. The final column allowed up to six tags. The template spreadsheet had no tags defined for any of its events, so I looked at TimelineJS’s web page for an explanation of tags in the FAQ section. TimelineJS uses tags to categorize events into groups, displayed on rows in the timeline. I decided to tag my events to test this feature. After working through the first row to create an event, I was able to add additional events more quickly. However, I was unable to add an event for which I did not have a specific date, only a year. For an event that occurred in 1924, I entered “1924” in the “Start Date” field, but the entry reverted to 4/7/1905. I was forced to add the event as occurring on January 1, 1924. I believe this is a fault of Google Sheets, not of TimelineJS.  (Note: I later discovered a TimelineJS FAQ entry explaining how to display only a month or year, which required converting the Google Sheets cell to plain text format.)  Along the way, I discovered my link problem was likely resulting from the fact that the template was created in an old version of Google Sheets. After I converted my spreadsheet to the new format, it worked.
  4. After filling out my spreadsheet, I returned to TimelineJS’s instructions. The next step was to use Google Sheets’s “Publish to the Web” command. The new version of Google Sheets used a different dialog box from TimelineJS’s screenshot, and the instructions were vague (such as, “Uncheck all other boxes.”), which left me confused as to which options to select. I published the spreadsheet without being sure I had selected the correct options and copied the URL Google then provided.
  5. Following the next step on TimelineJS’s website, I pasted my URL into a “generator box,” which I assumed generated the code needed to embed the timeline on a website. The generator offered options to adjust the timeline’s size. I could access more complex options by clicking a button; these allowed me to change the timeline’s language, font, and other features. The site provided font previews. . . except for the font I wanted to use.
  6. The final step instructed me to “grab” the resulting code to paste on my website. It also provided a preview button where I could see my timeline. However, I could not get the preview to load; it only displayed the message “still waiting on Google Docs, trying again.” I gave up on the preview and went to copy my code instead. The cursor turned to a crossed circle “Do Not Enter” symbol when I moused over the code box, but I was still able to copy my code.
  7. I first tested the code on my website hosted by Google Sites. The timeline would not display at all, even to the point of “still loading,” but after browsing the Community Support forum, I saw that other users had problems using the tool on Google Sites. I next tried placing the code on a plain HTML page which I tested from my hard drive. I got the same “still waiting” message I received from the preview. I then uploaded the HTML to a live server, but the error persisted. I checked the FAQ and found that I should have my spreadsheet set to “public” within Google Sheets—a step not included in the TimelineJS instructions. I changed the privacy settings and reloaded my HTML but still got the same error, which persisted after I republished my spreadsheet, regenerated the code, and tried loading the page in a different browser. I returned to the Community Support Forum, but although another user had posted the same problem, no one had responded. As the test timeline on the TimelineJS site loaded for me, I decided the problem must be with my spreadsheet, perhaps because I had converted it to the new Google Sheets format. I copied all the data from my new format spreadsheet, pasted it into the old format, and repeated the previous steps to construct my timeline. This time the preview worked, so I pasted the code into my HTML file and loaded the page and timeline successfully.
  8. The timeline itself seemed to work, but the images for my first three events showed as broken. I had linked to their lightbox view in Wikimedia Commons, so I changed my spreadsheet to include direct links to the image files. This change allowed me to test the Google Sheets option to automatically republish the spreadsheet when changes were made. Although I had selected this option, hard refreshing my timeline did not display the changes. Checking the image URL for the broken images showed the timeline was still drawing the link from the old spreadsheet data. However, when I pulled up the timeline’s iframe context menu and reloaded the frame itself, the images displayed correctly. Once loaded correctly, the images displayed resized to fit in the timeline. I would have liked for clicking on the image to show the full sized version, but that does not seem to be possible. At best, I would need to link to the original image within the caption, which is allowed. The YouTube video I embedded displayed, but the Google Map I included did not. I had used Google’s generated short URL for the map, and the map displayed when I changed it to the long form URL. However, the map showed up as stark black and white with no details. I returned to the customization options on the timeline generator and realized there were lots of options for how to display the map. However, changing the options did not update the code I could cut and paste. I had to hard-refresh the TimelineJS site and reinput the URL of my spreadsheet to adjust code options. Even then, I didn’t like the map display style and had to change it again. The unlabeled maps, including TimelineJS’s default selection, were all produced by Stamen Maps, so I changed to Google Maps. When everything finally displayed correctly, I tested the sizing and font options, all of which worked properly. However, changing the timeline’s display height to less than the default 650px resulted in the timeline displaying with a vertical scrollbar rather than resizing the content.
  9. In total, building my timeline and getting it to display correctly took approximately three hours. (I created a basic timeline featuring only eight events, without using the more complex development options available, such as JSON compatibility.) While I have never used a timeline tool before, I am experienced in spreadsheets, HTML, and basic web development, which leads me to wonder just how “intuitive” this tool is for a true novice user.