Configuring the Plugin

Last updated on
14 July 2017

The settings form, accessed by clicking the Settings link in your view's Format section, is divided into three sections. The TimelineJS Options and Additional Options sections contain settings for controlling the timeline presentation. The third section is where you add field mappings.

A field mapping tells Views to output one of the data fields to a specific TimelineJS object property. These mappings more or less conform to the fields in the TimelineJS Google Spreadsheet Template. Unlike in version 7.x-1.x of the module, the 3.x plugins do not restrict the types of Drupal data fields that may be used for mappings. You may use any type of field with any configuration and rewriting for any property, provided that the field output matches the type of data expected by TimelineJS, with a few exceptions.

Here is a list of the available mappings, with suggestions for the data fields you could use.

  • Headline - The selected field may contain any text, including HTML markup.

  • Body text - The selected field may contain any text, including HTML markup.

  • Start date - The selected field should contain a string representing a date conforming to a PHP supported date and time format.

    Start dates are required by event slides and eras. If this mapping is not configured or if the field does not output dates in a valid format, then the slides or eras will not be added to the timeline.

  • End date - The selected field should contain a string representing a date conforming to a PHP supported date and time format.

    End dates are required by eras. If this mapping is not configured or if the field does not output dates in a valid format, then the eras will not be added to the timeline.

  • Display date - The selected field should contain a string. TimelineJS will display this value instead of the values of the start and end date fields.

    This is possibly most useful for overriding the display of a Date field when you want to display a partial date. The Date module requires you to input a complete date with a year, month, and day value. That is because the MySQL datetime data type has this same restriction. If you want to display a partial date, e.g. "June 2016", then input 06/01/2016 into the date field, optionally giving it a range with an end date of 06/30/2016, then enter "June 2016" in the Display date field to format it the way you want.

  • Background image - The selected field should contain a raw URL to an image. Special handling is included for Image fields because they have no raw URL formatter.

    There is another contributed module, Image URL Formatter, that adds a field formatter for outputting a raw Image URL. You may use it if you want, but it should not be necessary with the special handling. Use the default Image field formatter and the plugin will extract the URL from the img tag's src attribute.

    Of course, Link fields or Text fields will work for this mapping, along with any other field that can output a string containing a raw URL to an image.

  • Media - The selected field should contain a raw URL to a media resource, an HTML blockquote, or an HTML iframe. See the media types documentation for a list of supported types. Special handling is included for Image fields because they have no raw URL formatter.

    See the Media Field Configuration section of this documentation for more information about how to set up entity fields and Views to include all supported types of media.

  • Media caption - The selected field may contain any text, including HTML markup.

  • Media credit - The selected field may contain any text, including HTML markup.

  • Group - The selected field may contain any text.

    The TimelineJS documentation makes no mention of HTML being allowed in group text, but it will be added to the output. This plugin does not strip tags from groups in order to allow you to format them if desired.

    If you use a Taxonomy reference field for this purpose, it is recommended that you format the field as Plain text, rather than as a Link. The links will not work correctly and they may cause the group text to be styled strangely.

  • Type - Determines the type of timeline entity that is rendered: event, title slide, or era. This plugin recognizes a limited set of string values to determine the type.

    • "title" or "timeline_title_slide" will cause a views data row to be rendered as a TimelineJS title slide. Only one title slide can be created per timeline. Additional title slides will overwrite previous slides.
    • "era" or "timeline_era" rows will be rendered as TimelineJS eras.
    • By default, a row with an empty value or any other input will be rendered as a regular event slide.

    Where these strings come from doesn't matter. You could create a content type with a List field configured with a radio button widget. Alternatively, you could create separate content types for events, title slides, and eras, making sure they have machine names that match the accepted values. Then add the Content: Type as a view field and map it to the Type property.

  • Unique ID - The selected field should contain a string value which is unique among all slides in your timeline, e.g. a node ID. If not specified, TimelineJS will construct an ID based on the headline, but if you later edit your headline, the ID will change. Unique IDs are used when the hash_bookmark option is used.

    If you don't need to make sure your slides have permanent links, you probably don't need to configure this mapping.

Help improve this page

Page status: No known problems

You can: