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 timeposition(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:
- Clone the repository
npm install
make test
License
MIT.