doc/doc.markdown in timeline_setter-0.3.0 vs doc/doc.markdown in timeline_setter-0.3.1
- old
+ new
@@ -28,31 +28,31 @@
The project is broken into two parts: a Ruby package (along with a binary) for
generating the assets, and the HTML, CSS and JavaScript for the timeline
itself. TimelineSetter will create a unique HTML page that embeds a JSON
object with your data. The CSS and JavaScript are identical for every timeline
created, so you can host those centrally and simply point to them when you
-deploy a timeline, or (with the minified option) you can package them up with your HTML
+deploy a timeline, or (with the minified option) you can package them up with your HTML
and paste it into your CMS all at once. You can [customize the CSS](#styling) to match the look
and feel of your site.
<a id="deps"></a>
## Dependencies
TimelineSetter relies on [TableFu](http://propublica.github.com/table-fu/), as
well as the JavaScript libraries
[Underscore](http://documentcloud.github.com/underscore/) and
[jQuery](http://jquery.com/). All of these are either installed along with
-TableSetter, or packaged with the source. It has been tested with jQuery 1.5.1
+TableSetter, or packaged with the source. It has been tested with jQuery 1.5.1
and Underscore 1.1.5.
<a id="install"></a>
## Installation
Install TimelineSetter through RubyGems on Unix-like OSes:
gem install timeline_setter
-
+
(Note: We haven't tested using the TimelineSetter tools on Windows even once,
though the timelines themselves have been tested in modern browsers on
Windows, Mac and Linux.)
<a id="commandline"></a>
@@ -63,11 +63,11 @@
static assets. At any point, you can find help by running `timeline-setter`
without any arguments, or by adding the `-h` flag. Run the command like so:
timeline-setter -c /path/to/data.csv -o /path/to/output/directory
-Running `timeline-setter` with no `-o` option will generate the timeline (and
+Running `timeline-setter` with no `-o` option will generate the timeline (and
supporting assets if applicable) within the current directory.
Full list of options:
* `-c CSV` Path to your CSV file.
@@ -139,14 +139,14 @@
|---timeline.html
|---javascripts
|-----timeline-setter.js
|-----vendor
|-------underscore-min.js
- |-------jquery-min.js
+ |-------jquery-min.js
|---stylesheets
|-----timeline-setter.css
-
+
Dropping the whole folder onto your server or an asset host like S3 will allow
the app to run self-contained. It requires no server-side processing at all.
To drop into your CMS, simply copy the relevant bits of `timeline.html` and
paste into your site's template. Then, adjust the `<link>` and `<script>` tags
to point to their appropriate destinations.
@@ -163,17 +163,18 @@
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 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;
+ var months = ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'];
+ defaults.month = months[d.getMonth()];
+ return defaults;
}
<a name="styling"></a>
@@ -212,28 +213,28 @@
hour/minute => 11:59
second => 11:59:22
<a id="interval_notch_options"></a>
The interval notches date spans themselves can be customized by using the `-i` flag when generating a timeline. The available parameters are
-
+
Decade
- Lustrum
+ Lustrum
FullYear
Month
- Week
- Date
- Hours
+ Week
+ Date
+ Hours
Minutes
Seconds
<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() {
+ currentTimeline.api.onLoad(function() {
console.log("I'm ready")
});
Here are the API methods:
@@ -243,14 +244,17 @@
### 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) {
+ currentTimeline.api.onCardAdd(function(evtName, obj, card) {
console.log(obj);
+ console.log(card);
});
+If you want to customize the card's template, set `card.template` to an undescore template function.
+
### 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
@@ -270,37 +274,56 @@
* Deactivating series checkboxes if none of its events are within the zoomed viewport
* Auto-zooming the timeline if embedded into smaller containers
* More iOS gestures such as "pinching"
* Zooming to fit a series when the series is activated
* Ranges of events (e.g. Elizabeth Taylor was married to Michael Wilding between
- Feb. 21, 1952 and Jan. 26, 1957, as shown
+ Feb. 21, 1952 and Jan. 26, 1957, as shown
[here](http://www.nytimes.com/interactive/2011/03/23/movies/20110323-ELIZABETH-TAYLOR-TIMELINE.html))
* Embed code
* JavaScript tests
-<a id="links"></a>
-## Links
+<a id="orgs"></a>
+## Media Organizations Using TimelineSetter
-* In the Wild: [ProPublica: How One Blast Affected Five Soldiers](http://www.propublica.org/special/tbi-psycho-platoon-timeline)
-* In the Wild: [TPM: The Wisconsin Union Struggle Timeline](http://www.talkingpointsmemo.com/interactive/2011/04/the-wisconsin-union-struggle-timeline.php)
-* In the Wild: [Los Angeles Times: Bell: 'Corruption on Steroids'](http://timelines.latimes.com/bell/)
+* [ProPublica](http://www.propublica.org/special/tbi-psycho-platoon-timeline)
+* [Los Angeles Times](http://timelines.latimes.com/bell/)
+* [Chicago Tribune](http://www.chicagotribune.com/news/local/chi-taxi-ts-docs-20111118,0,3641202.htmlstory)
+* [Huffington Post](http://www.huffingtonpost.com/2011/09/09/ground-zero-world-trade-center-freedom-tower_n_955845.html)
+* [Talking Points Memo](http://www.talkingpointsmemo.com/interactive/2011/04/the-wisconsin-union-struggle-timeline.php)
+* [MinnPost](http://www.minnpost.com/bachmanntimeline/)
+* [Milwaukee Journal-Sentinel](http://www.jsonline.com/news/129159038.html)
+* [WNYC](http://www.wnyc.org/articles/its-free-country/2011/may/20/timeline-gay-marriage-nystate/)
+* [ArtInfo](http://www.artinfo.com/news/story/37506/getting-to-know-ai-weiwei-a-multimedia-biographical-timeline/)
+* [Global TV News (Canada)](http://www.globalnews.ca/afghanistan/timeline/index.html?utm_source=facebook-twitter&utm_medium=link&utm_campaign=community)
+* [PBS Newshour](http://www.pbs.org/newshour/timeline/uprising/)
+* [American Public Media: Marketplace](http://www.marketplace.org/topics/economy/raising-debt-ceiling)
+* [San Antonio Express-News](http://blog.chron.com/rickperry/timeline-the-rise-of-rick-perry/)
+* [Voice of America](http://www.voanews.com/english/news/asia/southeast/Burma-Timeline-134760588.html#1183262400000-)
<a id="credits"></a>
## Credits
[Al Shaw](http://github.com/ashaw), [Jeff Larson](http://github.com/thejefflarson), ProPublica, [Ben Welsh](http://github.com/palewire), Los Angeles Times
<a id="contact"></a>
## Contact
-For issues with TimelineSetter, use the
-[Issue Tracker](https://github.com/propublica/timeline-setter/issues). General
+For issues with TimelineSetter, use the
+[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-031"></a>
+### 0.3.1
+
+* Fix position bug that was preventing card flipping in IE <= 8
+* Add `noscript` fallback
+* Add Century, HalfCentury, Quincenenary, HalfHour, QuarterHour, Millenium intervals
+* Fix CLI in cases where output directory already exists
+
<a id="release-030"></a>
### 0.3.0
* Add JavaScript API
* Scope timeline to a given element to support multiple timelines on a page
@@ -334,8 +357,8 @@
### 0.1.0
Initial release
<a id="license"></a>
-## License
+## License
-<%= license %>
\ No newline at end of file
+<%= license %>