doc/doc.markdown in timeline_setter-0.2.0 vs doc/doc.markdown in timeline_setter-0.3.0
- old
+ new
@@ -156,10 +156,28 @@
The timeline is made up of non-clickable *interval notches* used to denote
periods of time, and *event notches*, which, when clicked, reveal their
associated *event cards*.
+<a id="configuring"></a>
+## Configuring the Timeline JavaScript Embed
+
+Although the `timeline-setter` command generates a JavaScript embed that prepopulates your data, you can also create this yourself by calling `TimelineSetter.timeline.boot` with an array of card objects, and a config object.
+
+ var myTimeline = TimelineSetter.Timeline.boot([{card}...], {config})
+
+The config object looks for `interval`, `container`, and `formatter` options.
+
+The `interval` option takes an [interval](#interval_notch_options) in the form of a JavaScript date getter. The `container` option allows you to inject the entire timeline into an element with the given selector. (By default this is `#timeline`). Finally, `formatter` is a way to format dates on the timeline's interval notches. Write a formatter like so:
+
+ formatter : function(d, defaults) {
+ defaults.months = ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'];
+ return defaults;
+ }
+
+
+
<a name="styling"></a>
## Styling Your Timeline
TimelineSetter timelines are fully style-able. The default "ProPublica theme"
stylesheet is packaged alongside each generated asset bundle, and is available
@@ -167,34 +185,28 @@
replace it completely. Here's a guide to do that.
<a id="styling-container"></a>
### Overview and Styling the Container and Top Matter
-All TimelineSetter CSS is scoped within a namespace starting with `TS.` The
-outermost container is `#timeline_setter.`
+All TimelineSetter CSS is scoped within a namespace starting with `TS` except for the outermost container (by default `#timeline`.) The container is configurable with the `container` argument in the TimelineSetter boot function's config object.
Upon first glance, it may not seem like there is much markup at all. That's
because we make extensive use of JavaScript (ERB-style) templating via
-[Underscore.js](http://documentcloud.github.com/underscore/#template) -- so
-templates for each part of the timeline reside in the DOM. The controls (zoom
-in/out, previous/next buttons) are available within `#TS-top_matter_container .TS-controls`.
+[Underscore.js](http://documentcloud.github.com/underscore/#template) --
+templates for each part of the timeline reside in a JST object at the end of timeline-setter.js.
-Series checkboxes are injected into `.TS-series_nav_container` and templated
-via `script#TS-notch_tmpl`. Currently, series colors are hard coded in the
+Currently, series colors are hard coded in the
JavaScript. We support a maximum of nine series colors (assigned in this order:
``#065718, #EDC047, #91ADD1, #929E5E, #9E5E23, #C44846, #465363, #EDD4A5, #CECECE``,
they can be overridden in the "color priority" section of `timeline-setter.css`). Technically
you can create an unlimited number of series, but they will eventually fall back
to the default charcoal notch color.
<a id="styling-bar"></a>
### Styling the bar, notches and cards
-Interval notches are templated within `script#TS-year_notch_tmpl`. Their
-position is based on the interval of time between events as automatically
-determined by the JavaScript. Here's a sampling of what you might see in
-interval notches:
+The position of interval notches is based on the interval of time between events as automatically determined by the JavaScript. Here's a sampling of what you might see in interval notches:
year => 2001
month => June, 2004
day => May 1, 2005
hour/minute => 11:59
@@ -211,17 +223,46 @@
Date
Hours
Minutes
Seconds
-Event notches are templated through `#TS-card-tmpl` and contain individual
-classes corresponding to spreadsheet columns. `.TS-item-label` corresponds to
-`description`, `.TS-item_html` corresponds to `html`,
-`.TS-read_btn` is linked to `link` and `.TS-item_year` corresponds to
-`display_date` falling through to `date`. Finally, `TS-permalink`
-is a fragment link which will show the active card on page load if used.
+<a id="js_api"></a>
+## The JavaScript API
+As of version 0.3.0, TimelineSetter has a JavaScript API that allows programmatic access to certain events, and the ability to activate cards. To use the API, assign the `TimelineSetter.Timeline.boot()` function to a variable, and then use methods in the `api` object like so:
+
+ var currentTimeline = TimelineSetter.Timeline.boot(options);
+ currentTimeline.api.onLoad(function() {
+ console.log("I'm ready")
+ });
+
+Here are the API methods:
+
+### onLoad
+
+Register a callback for when the timeline is loaded.
+
+### onCardAdd
+
+Register a callback for when a card is added to the timeline. This method has access to the event name and the card object.
+
+ currentTimeline.api.onCardAdd(function(evtName, obj) {
+ console.log(obj);
+ });
+
+### onCardActivate
+
+Register a callback for when a card is activated (i.e. shown). This method has access to the event name and the card object.
+
+### onBarMove
+
+Register a callback for when the bar is moved or zoomed. Be careful with this one: Bar move events can be fast and furious, especially with scroll wheels in Safari.
+
+### activateCard
+
+Show the card matching a given timestamp. Right now, timelines only support one card per timestamp.
+
<a id="roadmap"></a>
## Roadmap
On the client side, there are a number of features we plan to add, including:
@@ -255,9 +296,16 @@
[Issue Tracker](https://github.com/propublica/timeline-setter/issues). General
questions should go to <a href="mailto:opensource@propublica.org">opensource@propublica.org</a>.
<a id="changelog"></a>
## Change Log
+
+<a id="release-030"></a>
+### 0.3.0
+
+* Add JavaScript API
+* Scope timeline to a given element to support multiple timelines on a page
+* Add date formatter config option. _Thanks [@omega](https://github.com/propublica/timeline-setter/pull/26)_
<a id="release-020"></a>
### 0.2.0
* New feature adds support for custom interval notch ranges.
\ No newline at end of file