How to install and use Views TimelineJS

Last updated on

16 August 2022

Installation

Download the module and enable it. By default, there are no library files to download because they are served from the NU Knight Lab CDN.

Optional: If you want to serve the library files from your own site instead of the CDN, then you need to download the library files. You MUST put the TimelineJS library in the /libraries directory inside your Drupal installation. Alternate library locations such as those checked by the Libraries API module will not work.

If you want to serve the library files from your own site instead of the CDN, then you need to download them. ZIP files of the compiled library are available. You may download a specific version from https://cdn.knightlab.com/libs/timeline3/VERSION-NUMBER/timeline3.zip, for example:

The timeline.js and timeline.css files are required to use TimelineJS. The library also includes several font library CSS files that must be downloaded if you want to use them. In the end, you need to have the following files in these directories:

/libraries/timeline3/js/timeline.js
/libraries/timeline3/css/timeline.css
/libraries/timeline3/css/fonts/font.FONT-NAME.css (optional)

Other methods of downloading the library will not be supported. Previously these instructions recommended cloning the library's repository from GitHub, but the repo no longer contains the compiled files.

Upgrading

If you are upgrading this module from version 7.x-1.x then make sure you test your view and reconfigure it before deploying to a production environment! Much of the plugin's functionality was changed in the upgrade to TimelineJS3. Version 3 of the library offers several nice enhancements over version 2. The plugin has received a lot of updates in order to take full advantage of the new library. Some settings have been changed or removed. New settings have been added. The fact that the Date field setting has been split into separate Start date and End date field settings means that all existing views that were built with version 7.x-1.x will need to be reconfigured for 8.x-3.x.

Using the Plugin

Create a new view and change the display format to "TimelineJS".
Click "Add" in the Fields section of the Views interface to add all the desired fields to the view. Once fields have been added, they will be available for field mappings.
Format the fields used for the timeline as desired. For example, if you want the headline to link to the entity it represents use the "Link this field to the original piece of content" option in the field's settings. Likewise if you want to strip tags from the body text, use the "Rewrite results" -> "Strip HTML tags" option in that field's settings.
Click the Settings link in the Format section. Edit the general configuration of the timeline display. Then add field mappings. Start dates are required by event slides and eras. End dates are also required by eras. If these mappings are not configured or if the fields do not contain dates in a valid format, then the slides or eras will not be added to the timeline. See the documentation on Configuring the Plugin for more information.
Click "Save" in the view to complete the configuration. The preview display on the Views edit interface shows the data used by TimelineJS. To see the TimelineJS display, access the view page that was just created.

About the "Start at Current" Setting

The "Start at Current" setting is an option that is unique to this Views plugin. It will cause the timeline to load on the slide that is closest to the current date and time. In order for it to work correctly, you must configure your View to sort the slides by Start Date ascending. If you do not, the TimelineJS library will sort the slides into chronological order and the calculated start slide will not match its new position in the order.

Known Issue with Twig Debugging

Enabling Twig Debugging for development may cause issues with some fields being rendered incorrectly. Specifically, there is a known issue with background colors not being rendered and another issue with Unique IDs causing debug output to be rendered in URLs. Debugging comments are rendered in the field, causing the problem. Although the issue has only been reported for two field types so far, it is possible that the problem could effect other fields for which TimelineJS expects a specific type of data rather than any HTML. This problem is part of a larger known issue with Views.