-
Notifications
You must be signed in to change notification settings - Fork 70
/
index.html
542 lines (394 loc) · 20.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link href="http://cloud.webtype.com/css/50942e7d-aebe-4c83-9824-ead7e49ec5af.css" rel="stylesheet" type="text/css" />
<style>
html {
background: #f7f7f7;
}
body {
font-family: Georgia, serif;
font-size: 16px;
line-height:24px;
width: 600px;
margin-left:auto;
margin-right:auto;
margin-top:10px;
background: #fff;
padding:10px 10px;
color:#444;
border-top:1px solid #cecece;
border-bottom:1px solid #cecece;
}
h1,h2,h3,h4,h5 {
font-family: 'Helvetica Neue', Arial, sans-serif;
color:#444;
}
h1 {
padding-top:0;
margin-top:0;
}
h2,h3 {
}
a.propublica{
position:absolute;
background: transparent url(http://propublica.github.com/table-fu/documentation/images/proplogo.png) no-repeat -40px -20px;
top: 0;
left: 0;
width: 160px;
height: 141px;
}
pre,code {
font-family: Monaco, Courier, monospace;
font-size:12px;
}
pre {
line-height: 16px;
padding:0.5em 1em;
overflow: auto;
border-left: 1px solid #cecece;
margin-left: 0;
background:#f7f7f7;
}
code {
padding: 2px;
background-color: #f7f7f7;
}
pre > code {
padding:0;
}
a {
color: #4369AF;
text-decoration: none;
font-weight: bold;
}
a:hover {
text-decoration:underline;
}
ul {
margin:0 1em;
padding:0;
list-style: disc;
}
li {
margin:0;
padding:0;
}
</style>
<title>TimelineSetter</title>
</head>
<body>
<a href="http://www.propublica.org" class="propublica"> </a>
<h1>TimelineSetter 0.3.2</h1>
<p>TimelineSetter creates beautiful timelines.</p>
<p>It is a command-line utility that takes a <a href="#csv">specially-structured CSV file</a>
as input and outputs standards-compliant HTML/CSS/JavaScript. It supports any
span of time from minutes to years, and supports multiple parallel event
series in a single timeline. It can handle custom descriptions and even
arbitrary HTML in each event “card.” It creates fluid embeds that will look
great at any width.</p>
<p>TimelineSetter “bakes out” timelines, ready for uploading directly into your
CMS, Amazon S3, or however you typically serve static files. It requires no
server-side processing at all once you’ve generated a timeline.</p>
<p>TimelineSetter <a href="https://github.com/propublica/timeline-setter/">source on Github</a>.</p>
<p><a id="samples"></a></p>
<h2>Assorted Docs and Samples</h2>
<ul>
<li>TimelineSetter Ruby source <a href="documentation/index.html">documentation</a></li>
<li>timeline-setter.js <a href="doc/timeline-setter.html">annotated source</a></li>
<li>A <a href="doc/twitter-demo.html">TimelineSetter demo</a> using Twitter data</li>
</ul>
<p><a id="innards"></a></p>
<h2>How it Works</h2>
<p>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
and paste it into your CMS all at once. You can <a href="#styling">customize the CSS</a> to match the look
and feel of your site.</p>
<p><a id="deps"></a></p>
<h2>Dependencies</h2>
<p>TimelineSetter relies on <a href="http://propublica.github.com/table-fu/">TableFu</a>, as
well as the JavaScript libraries
<a href="http://documentcloud.github.com/underscore/">Underscore</a> and
<a href="http://jquery.com/">jQuery</a>. All of these are either installed along with
TableSetter, or packaged with the source. It has been tested with jQuery 1.5.1
and Underscore 1.1.5.</p>
<p><a id="install"></a></p>
<h2>Installation</h2>
<p>Install TimelineSetter through RubyGems on Unix-like OSes:</p>
<pre><code>gem install timeline_setter
</code></pre>
<p>(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.)</p>
<p><a id="commandline"></a></p>
<h2>The `timeline-setter` command</h2>
<p>After TimelineSetter is installed, the <code>timeline-setter</code> command should be
available in your shell. The command looks for a CSV file to parse and outputs
static assets. At any point, you can find help by running <code>timeline-setter</code>
without any arguments, or by adding the <code>-h</code> flag. Run the command like so:</p>
<pre><code>timeline-setter -c /path/to/data.csv -o /path/to/output/directory
</code></pre>
<p>Running <code>timeline-setter</code> with no <code>-o</code> option will generate the timeline (and
supporting assets if applicable) within the current directory.</p>
<p>Full list of options:</p>
<ul>
<li><code>-c CSV</code> Path to your CSV file.</li>
<li><code>-o OUTPUT_PATH</code> Path to output timeline and assets. If absent, timeline will be created in current directory.</li>
<li><code>-a</code> Do not output supporting assets such as CSS and JavaScript. This is useful if you’re customizing those and don’t want your versions clobbered.</li>
<li><code>-m</code> Create a minified one-page version of your timeline with all supporting assets inline.</li>
<li><code>-O</code> Open a browser to your new timeline after it is generated (currently Mac OS only).</li>
<li><code>-i</code> Add a custom interval for background “interval notches.” These take the format of JavaScript date <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date#Methods">getter methods</a>. For example, year would be <code>FullYear.</code> All the options are available <a href="#interval_notch_options">below</a>. If absent, TimelineSetter will attempt to automatically create interval notches based on the first and last dates in your timeline.</li>
<li><code>-h</code> Print help to standard output.</li>
</ul>
<p><a id="csv"></a></p>
<h2>Setting Up Your CSV File</h2>
<p>TimelineSetter looks for certain column names in your CSV file in order to
generate a timeline. All columns are required, though as you’ll see, some of
them can be left blank (see a <a href="https://github.com/propublica/timeline-setter/blob/master/spec/test_data.csv">sample CSV</a>). Here’s a summary of each column and its significance:</p>
<p><a id="date-csv"></a></p>
<h3>date</h3>
<p>The date the event happened. Right now, TimelineSetter only supports
single-date events, but this can be specific down to the second. The generator
will try its best to parse out human dates. Try “March 20, 2010,” “3/20/2010,”
“Mar. 20, 2010 11:59 PM” etc.</p>
<p><a id="display-date-csv"></a></p>
<h3>display_date</h3>
<p>The date <em>displayed</em> on the event’s card in the timeline. If this is blank, it
will fall back to <code>date</code></p>
<p><a id="desc-csv"></a></p>
<h3>description</h3>
<p>A description of the event.</p>
<p><a id="link-csv"></a></p>
<h3>link</h3>
<p>A URL to send users to more details about an event. This will generate a “read
more” button at the bottom of the card pointing to the URL.</p>
<p><a id="series-csv"></a></p>
<h3>series</h3>
<p>A string representing the name of the series of events this particular event
is a part of. TimelineSetter will find all the unique series among events in
the spreadsheet and assign both colors and checkboxes for them at the top of
the spreadsheet. Events not assigned to a series will be part of the “default”
series, which have their timeline notches colored charcoal, and have no
associated checkbox. <strong>Note:</strong> As a corollary, if you only have one series, it is
best not to assign a name.</p>
<p><a id="html-csv"></a></p>
<h3>html</h3>
<p>Any arbitrary HTML that will be inserted above <code>description</code>. This
field may contain image tags, YouTube tags, etc. — nearly everything except
<code><script></code> tags. If you choose to use JavaScript, you must do it inside an
iframe and call that iframe inside this field. <strong>Note</strong>: If you put an image or iframe in this field, make sure to set <code>height</code> and <code>width</code> attributes, or the card may not extend around the image.</p>
<p><a id="deployment"></a></p>
<h2>Folder structure and deployment</h2>
<p>After you’ve generated a timeline with the <code>timeline-setter</code> command, you
should see a structure much like this where you’ve specified your output:</p>
<pre><code> |-output
|---timeline.html
|---javascripts
|-----timeline-setter.js
|-----vendor
|-------underscore-min.js
|-------jquery-min.js
|---stylesheets
|-----timeline-setter.css
</code></pre>
<p>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 <code>timeline.html</code> and
paste into your site’s template. Then, adjust the <code><link></code> and <code><script></code> tags
to point to their appropriate destinations.</p>
<p><a id="defn"></a></p>
<h2>Definitions</h2>
<p>The timeline is made up of non-clickable <em>interval notches</em> used to denote
periods of time, and <em>event notches</em>, which, when clicked, reveal their
associated <em>event cards</em>.</p>
<p><a id="configuring"></a></p>
<h2>Configuring the Timeline JavaScript Embed</h2>
<p>Although the <code>timeline-setter</code> command generates a JavaScript embed that prepopulates your data, you can also create this yourself by calling <code>TimelineSetter.timeline.boot</code> with an array of card objects, and a config object.</p>
<pre><code>var myTimeline = TimelineSetter.Timeline.boot([{card}...], {config})
</code></pre>
<p>The config object looks for <code>interval</code>, <code>container</code>, and <code>formatter</code> options.</p>
<p>The <code>interval</code> option takes an <a href="#interval_notch_options">interval</a> in the form of a JavaScript date getter. The <code>container</code> option allows you to inject the entire timeline into an element with the given selector. (By default this is <code>#timeline</code>). Finally, <code>formatter</code> is a way to format dates on the timeline’s interval notches. Write a formatter like so:</p>
<pre><code>formatter : function(d, defaults) {
var months = ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'];
defaults.month = months[d.getMonth()];
return defaults;
}
</code></pre>
<p><a name="styling"></a></p>
<h2>Styling Your Timeline</h2>
<p>TimelineSetter timelines are fully style-able. The default “ProPublica theme”
stylesheet is packaged alongside each generated asset bundle, and is available
in <code>stylesheets/timeline-setter.css</code>. You can alter this stylesheet, or
replace it completely. Here’s a guide to do that.</p>
<p><a id="styling-container"></a></p>
<h3>Overview and Styling the Container and Top Matter</h3>
<p>All TimelineSetter CSS is scoped within a namespace starting with <code>TS</code> except for the outermost container (by default <code>#timeline</code>.) The container is configurable with the <code>container</code> argument in the TimelineSetter boot function’s config object.</p>
<p>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
<a href="http://documentcloud.github.com/underscore/#template">Underscore.js</a> —
templates for each part of the timeline reside in a JST object at the end of timeline-setter.js.</p>
<p>Currently, series colors are hard coded in the
JavaScript. We support a maximum of nine series colors (assigned in this order:
<code>#065718, #EDC047, #91ADD1, #929E5E, #9E5E23, #C44846, #465363, #EDD4A5, #CECECE</code>,
they can be overridden in the “color priority” section of <code>timeline-setter.css</code>). Technically
you can create an unlimited number of series, but they will eventually fall back
to the default charcoal notch color.</p>
<p><a id="styling-bar"></a></p>
<h3>Styling the bar, notches and cards</h3>
<p>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:</p>
<pre><code>year => 2001
month => June, 2004
day => May 1, 2005
hour/minute => 11:59
second => 11:59:22
</code></pre>
<p><a id="interval_notch_options"></a>
The interval notches date spans themselves can be customized by using the <code>-i</code> flag when generating a timeline. The available parameters are</p>
<pre><code>Decade
Lustrum
FullYear
Month
Week
Date
Hours
Minutes
Seconds
</code></pre>
<p><a id="js_api"></a></p>
<h2>The JavaScript API</h2>
<p>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 <code>TimelineSetter.Timeline.boot()</code> function to a variable, and then use methods in the <code>api</code> object like so:</p>
<pre><code>var currentTimeline = TimelineSetter.Timeline.boot(options);
currentTimeline.api.onLoad(function() {
console.log("I'm ready")
});
</code></pre>
<p>Here are the API methods:</p>
<h3>onLoad</h3>
<p>Register a callback for when the timeline is loaded.</p>
<h3>onCardAdd</h3>
<p>Register a callback for when a card is added to the timeline. This method has access to the event name and the card object.</p>
<pre><code>currentTimeline.api.onCardAdd(function(evtName, obj, card) {
console.log(obj);
console.log(card);
});
</code></pre>
<p>If you want to customize the card’s template, set <code>card.template</code> to an undescore template function.</p>
<h3>onCardActivate</h3>
<p>Register a callback for when a card is activated (i.e. shown). This method has access to the event name and the card object.</p>
<h3>onBarMove</h3>
<p>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.</p>
<h3>activateCard</h3>
<p>Show the card matching a given timestamp. Right now, timelines only support one card per timestamp.</p>
<p><a id="roadmap"></a></p>
<h2>Roadmap</h2>
<p>On the client side, there are a number of features we plan to add, including:</p>
<ul>
<li>Smoother zooming</li>
<li>Deactivating series checkboxes if none of its events are within the zoomed viewport</li>
<li>Auto-zooming the timeline if embedded into smaller containers</li>
<li>More iOS gestures such as “pinching”</li>
<li>Zooming to fit a series when the series is activated</li>
<li>Ranges of events (e.g. Elizabeth Taylor was married to Michael Wilding between
Feb. 21, 1952 and Jan. 26, 1957, as shown
<a href="http://www.nytimes.com/interactive/2011/03/23/movies/20110323-ELIZABETH-TAYLOR-TIMELINE.html">here</a>)</li>
<li>Embed code</li>
<li>JavaScript tests</li>
</ul>
<p><a id="orgs"></a></p>
<h2>Media Organizations Using TimelineSetter</h2>
<ul>
<li><a href="http://www.propublica.org/special/tbi-psycho-platoon-timeline">ProPublica</a></li>
<li><a href="http://timelines.latimes.com/bell/">Los Angeles Times</a></li>
<li><a href="http://www.chicagotribune.com/news/local/chi-taxi-ts-docs-20111118,0,3641202.htmlstory">Chicago Tribune</a></li>
<li><a href="http://www.huffingtonpost.com/2011/09/09/ground-zero-world-trade-center-freedom-tower_n_955845.html">Huffington Post</a></li>
<li><a href="http://www.talkingpointsmemo.com/interactive/2011/04/the-wisconsin-union-struggle-timeline.php">Talking Points Memo</a></li>
<li><a href="http://www.minnpost.com/bachmanntimeline/">MinnPost</a></li>
<li><a href="http://www.jsonline.com/news/129159038.html">Milwaukee Journal-Sentinel</a></li>
<li><a href="http://www.wnyc.org/articles/its-free-country/2011/may/20/timeline-gay-marriage-nystate/">WNYC</a></li>
<li><a href="http://www.artinfo.com/news/story/37506/getting-to-know-ai-weiwei-a-multimedia-biographical-timeline/">ArtInfo</a></li>
<li><a href="http://www.globalnews.ca/afghanistan/timeline/index.html?utm_source=facebook-twitter&utm_medium=link&utm_campaign=community">Global TV News (Canada)</a></li>
<li><a href="http://www.pbs.org/newshour/timeline/uprising/">PBS Newshour</a></li>
<li><a href="http://www.marketplace.org/topics/economy/raising-debt-ceiling">American Public Media: Marketplace</a></li>
<li><a href="http://blog.chron.com/rickperry/timeline-the-rise-of-rick-perry/">San Antonio Express-News</a></li>
<li><a href="http://www.voanews.com/english/news/asia/southeast/Burma-Timeline-134760588.html#1183262400000-">Voice of America</a></li>
<li><a href="http://www.effecinque.org/wp/processo-assange-timeline.html">effecinque</a></li>
</ul>
<p><a id="credits"></a></p>
<h2>Credits</h2>
<p><a href="http://github.com/ashaw">Al Shaw</a>, <a href="http://github.com/thejefflarson">Jeff Larson</a>, ProPublica, <a href="http://github.com/palewire">Ben Welsh</a>, Los Angeles Times</p>
<p><a id="contact"></a></p>
<h2>Contact</h2>
<p>For issues with TimelineSetter, use the
<a href="https://github.com/propublica/timeline-setter/issues">Issue Tracker</a>. General
questions should go to <a href="mailto:opensource@propublica.org">opensource@propublica.org</a>.</p>
<p><a id="changelog"></a></p>
<h2>Change Log</h2>
<p><a id="release-032"></a></p>
<h3>0.3.2</h3>
<ul>
<li>Fix reliance on jQuery’s <code>.toggle(handler, handler)</code> which was deprecated in 1.8</li>
</ul>
<p><a id="release-031"></a></p>
<h3>0.3.1</h3>
<ul>
<li>Fix position bug that was preventing card flipping in IE <= 8</li>
<li>Add <code>noscript</code> fallback</li>
<li>Add Century, HalfCentury, Quincenenary, HalfHour, QuarterHour, Millenium intervals</li>
<li>Fix CLI in cases where output directory already exists</li>
</ul>
<p><a id="release-030"></a></p>
<h3>0.3.0</h3>
<ul>
<li>Add JavaScript API</li>
<li>Scope timeline to a given element to support multiple timelines on a page</li>
<li>Add date formatter config option. <em>Thanks <a href="https://github.com/propublica/timeline-setter/pull/26">@omega</a></em></li>
</ul>
<p><a id="release-020"></a></p>
<h3>0.2.0</h3>
<ul>
<li>New feature adds support for custom interval notch ranges.</li>
<li>Change command line to output supporting assets by default unless <code>-a</code> is specified</li>
</ul>
<p><a id="release-012"></a></p>
<h3>0.1.2</h3>
<ul>
<li>Support for decade and lustrum (five year period) interval notches. <em>Thanks, <a href="http://github.com/palewire">Ben Welsh</a></em></li>
</ul>
<p><a id="release-011"></a></p>
<h3>0.1.1</h3>
<ul>
<li>Made JavaScript smarter about image widths, so now images can be used without specifying height and width attributes</li>
<li>Fixed “read more” buttons so they can be clicked everywhere, not just on the text</li>
<li>Fixed a CLI bug where timeline was being put in the wrong place when output directory is specified without a trailing slash</li>
<li>Fixed duplicate colors in CSS</li>
<li>Fixed layout rendering problems when a card was more than half the size of the timeline</li>
<li>Fixed an issue where JSON couldn’t be generated in Ruby 1.9</li>
</ul>
<p><em>Thanks to <a href="http://github.com/palewire">Ben Welsh</a> for pointing out most of these issues</em></p>
<p><a id="release-010"></a></p>
<h3>0.1.0</h3>
<p>Initial release</p>
<p><a id="license"></a></p>
<h2>License</h2>
<p>Copyright © 2011 ProPublica</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
</body>
</html>