Skip to content

Latest commit

 

History

History
149 lines (101 loc) · 3.84 KB

API.md

File metadata and controls

149 lines (101 loc) · 3.84 KB

TimelineJS3 API

Timeline 3 exposes the events and methods listed below.

Note that these methods make a distinction between an event_index and a slide_index. An event_index is an index into the sorted array of events in the timeline data object. A slide_index is index of the slide that appears in the rendered timeline.

A title has no event_index and has slide_index 0.

If you have a title, the first event has event_index 0 and slide_index 1.

If you do not have a title, the first event has event_index 0 and slide_index 0.

Events

// Create new Timeline object
var timeline = new TL.Timeline(...);

// Set event handlers
// event_name = string, name of the event, e.g. "change"
// data = JavaScript object containing event-specific properties listed below
timeline.on(event_name, function(data) {
    // handle event
});

back_to_start when user clicks control to return to beginning of timeline

change when the current slide changes

  • unique_id: string, id of the new current slide

color_change when background of current slide changes

  • unique_id: string, id of the new current slide

dataloaded after data has been loaded

hash_updated when the hashbookmack in the url bar is updated

  • unique_id: string, id of the new current slide
  • hashbookmark: string, the hash

loaded after story slider and time navigator have been loaded

  • scale: "human" or "cosmological", the type of date scale
  • eras: array
  • events: array
  • title: title slide data, if title slide exists

zoom_in when user zooms in the time navigator

zoom_out when user zooms out the time navigator

  • zoom_level: integer, current zoom level

added after slide has been added

removed after slide has been removed

  • unique_id: string, the id of the modified slide

nav_next fires when next button is clicked

nav_previous fires when next button is clicked

Navigation

goTo(<int slide_index>) go to slide at index

goToId(<string id>) go to slide with id

goToNext() go to next slide

goToPrev() go to previous slide

goToStart() go to first slide

goToEnd() go to last slide

Manipulation

remove(<int event_index>) remove event by index

removeId(<string id>) remove event by id

add(<object data>) add event with data (see event data format below)

Data Access

getData(<int slide_index>) get data for slide by index

getDataById(<string id>) get data for slide by id

getSlide(<int slide_index>) get TL.Slide object by index

getSlideById(<string id>) get TL.Slide object by id

Event data format

{
    "start_date": {
        "year":			<string>, // all events must have a year. 
        "month":		<string>, // other attributes are optional
        "day": 			<string>, 
        "hour": 		<string>,
        "minute": 		<string>,
        "second": 		<string>,
        "millisecond": 	<string>,
        "format": 		<string>,
        "display_text": <string>
    },
    "end_date": {                   // optional
        "year":			<string>,
        "month":		<string>,
        "day": 			<string>,
        "hour": 		<string>,
        "minute": 		<string>,
        "second": 		<string>,
        "millisecond": 	<string>,
        "format": 		<string>,
        "display_text": <string>
    },
    "location": {                   // optional
        "icon":         <string>,   // icon url
        "lat":          <float>,   
        "lon":          <float>,
        "line":         <boolean>,
        "name":         <string>,
        "zoom":         <int>
    },
    "media": {
        "caption":      <string>,
        "credit":       <string>,
        "url":          <string>,
        "thumbnail":    <string>
    },
    "text": {
        "headline":     <string>,
        "text":         <string>
    },
    "unique_id":         <string>    // optional
};