timeline

timeline copied to clipboard

Installation

Node:

npm install timeline

Timeline = require 'timeline'

Browser:

<script src="/path/to/timeline.js"></script>

Usage

To create a timeline using the default options:

timeline = new Timeline

You can also pass in options:

timeline = new Timeline
  length: 5000
  frequency: 250

The defaults are:

length: 0
frequency: 100

length is the total length of the timeline. frequency is how often tick events are fired when the timeline is playing. All values are in milliseconds.

Markers

A Timeline object contains an Array of markers. Markers are objects with three properties:

time

The time in milliseconds on the timeline where the marker should live.

forward

The function to execute when moving forward in time through the marker.

backward

The function to execute when moving backward in time through the marker.

timeline.markers.push
  time: 500
  forward: ->
    $('.elements').show()
  backward: ->
    $('.elements').hide()

Methods

All getters return the expected value. Every other method returns the Timeline object for chaining.

play()

Begins playing the timeline, triggering markers as it goes.

pause()

Stops playing the timeline.

length()

Returns the length of the timeline.

length(ms)

Sets the length of the timeline to ms.

frequency()

Returns the frequency.

frequency(ms)

Sets the frequency to ms.

position()

Returns the current position of the timeline.

position(ms)

Jumps to the new position at ms.

Events

Timelines also have three methods for events:

on(event, callback)

Binds the callback function to the event.

off(event[, callback])

Unbinds event callbacks. If a callback is passed in as the second argument, only that callback is unbound. If there is no second argument, all callbacks for that event are unbound.

trigger(event, args...)

Triggers all callbacks bound to the event. Any extra parameters are passed as parameters to the callbacks.

Timelines emit these events:

play

Triggered whenever a timeline starts playing.

pause

Triggered whenever a timeline pauses.

end

Triggered if the timeline hits the end.

tick

Triggered every frequency milliseconds while a timeline is playing, and once every time position(ms) is used, regardless of whether the timeline is playing or not.

timeline = new Timeline length:4000
timeline.on 'tick', ->
  $('.current-time').text timeline.position()

Other Properties

playing

True if the timeline is playing, false otherwise.

Development + Tests

Tests are written in CoffeeScript using Mocha and should.js. To run them:

1. Clone the repository
2. npm install
3. make test

License

MIT.