timeline_setter 0.2.0 → 0.3.0

data/Rakefile

@@ -5,6 +5,16 @@ require 'rake/rdoctask'
 require 'rspec/core/rake_task'
 require './lib/timeline_setter'
 
+desc "generate templates and minified JS. Stash them in public/javascripts"
+task :jammit do
+  %x{
+    cd #{TimelineSetter::ROOT} && 
+    jammit && 
+    mv public/assets/templates.js public/javascripts/templates.js && 
+    mv public/assets/main.js public/javascripts/timeline-setter.min.js
+    rm -rf public/assets
+  }
+end
 
 desc "build docs"
 task :docs do 
@@ -24,7 +34,6 @@ task :gh_pages do
   `rake docs`
   `rake yard`
   `rake docco`
-  `rake sample`
 
   `git branch` =~ /^\* (.+)?\n/
   current_branch = $1
@@ -58,7 +67,7 @@ begin
     gem.add_dependency "json"
     gem.add_dependency "table_fu"
     gem.add_dependency "kompress", ">= 0.0.2"
-    gem.add_dependency "closure-compiler"
+    gem.add_dependency "jammit"
     gem.add_development_dependency "rspec", ">= 2.0.0"
     gem.version = TimelineSetter::VERSION
   end

data/config/assets.yml

@@ -0,0 +1,9 @@
+embed_assets :on
+template_function: _.template
+
+javascripts:
+  main:
+    - public/javascripts/timeline-setter.js
+    - public/javascripts/templates/*.jst
+  templates:
+    - public/javascripts/templates/*.jst

data/doc/doc.markdown

@@ -158,6 +158,24 @@ 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
 
@@ -169,17 +187,14 @@ 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
@@ -189,10 +204,7 @@ 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
@@ -213,12 +225,41 @@ The interval notches date spans themselves can be customized by using the `-i` f
     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
@@ -258,6 +299,13 @@ questions should go to <a href="mailto:opensource@propublica.org">opensource@pro
 <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
 

data/doc/templates.html

@@ -0,0 +1,3 @@
+<!DOCTYPE html>  <html> <head>   <title>templates.js</title>   <meta http-equiv="content-type" content="text/html; charset=UTF-8">   <link rel="stylesheet" media="all" href="docco.css" /> </head> <body>   <div id="container">     <div id="background"></div>            <div id="jump_to">         Jump To &hellip;         <div id="jump_wrapper">           <div id="jump_page">                                           <a class="source" href="templates.html">                 templates.js               </a>                                           <a class="source" href="timeline-setter.html">                 timeline-setter.js               </a>                                           <a class="source" href="timeline-setter.min.html">                 timeline-setter.min.js               </a>                        </div>         </div>       </div>          <table cellpadding="0" cellspacing="0">       <thead>         <tr>           <th class="docs">             <h1>               templates.js             </h1>           </th>           <th class="code">           </th>         </tr>       </thead>       <tbody>                               <tr id="section-1">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-1">&#182;</a>               </div>                            </td>             <td class="code">               <div class="highlight"><pre><span class="p">(</span><span class="kd">function</span><span class="p">(){</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="o">=</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="o">||</span><span class="p">{};</span><span class="kd">var</span> <span class="nx">a</span><span class="o">=</span><span class="kd">function</span><span class="p">(</span><span class="nx">c</span><span class="p">){</span><span class="kd">var</span> <span class="nx">b</span><span class="o">=</span><span class="k">new</span> <span class="nb">Function</span><span class="p">(</span><span class="s2">&quot;obj&quot;</span><span class="p">,</span><span class="s2">&quot;var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push(&#39;&quot;</span><span class="o">+</span><span class="nx">c</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\\/g</span><span class="p">,</span><span class="s2">&quot;\\\\&quot;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/&#39;/g</span><span class="p">,</span><span class="s2">&quot;\\&#39;&quot;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/&lt;%=([\s\S]+?)%&gt;/g</span><span class="p">,</span><span class="kd">function</span><span class="p">(</span><span class="nx">d</span><span class="p">,</span><span class="nx">e</span><span class="p">){</span><span class="k">return</span><span class="s2">&quot;&#39;,&quot;</span><span class="o">+</span><span class="nx">e</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\\&#39;/g</span><span class="p">,</span><span class="s2">&quot;&#39;&quot;</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot;,&#39;&quot;</span><span class="p">}).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/&lt;%([\s\S]+?)%&gt;/g</span><span class="p">,</span><span class="kd">function</span><span class="p">(</span><span class="nx">d</span><span class="p">,</span><span class="nx">e</span><span class="p">){</span><span class="k">return</span><span class="s2">&quot;&#39;);&quot;</span><span class="o">+</span><span class="nx">e</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\\&#39;/g</span><span class="p">,</span><span class="s2">&quot;&#39;&quot;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/[\r\n\t]/g</span><span class="p">,</span><span class="s2">&quot; &quot;</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot;__p.push(&#39;&quot;</span><span class="p">}).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\r/g</span><span class="p">,</span><span class="s2">&quot;\\r&quot;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\n/g</span><span class="p">,</span><span class="s2">&quot;\\n&quot;</span><span class="p">).</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\t/g</span><span class="p">,</span><span class="s2">&quot;\\t&quot;</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot;&#39;);}return __p.join(&#39;&#39;);&quot;</span><span class="p">);</span><span class="k">return</span> <span class="nx">b</span><span class="p">};</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="p">.</span><span class="nx">card</span><span class="o">=</span><span class="nx">a</span><span class="p">(</span><span class="s1">&#39;&lt;div class=&quot;TS-card_container TS-card_container_&lt;%= (card.get(&quot;series&quot;) || &quot;&quot;).replace(/W/g, &quot;&quot;) %&gt;&quot;&gt;\n&lt;div class=&quot;TS-css_arrow TS-css_arrow_up TS-css_arrow_color_&lt;%= card.get(&quot;topcolor&quot;) %&gt;&quot;&gt;&lt;/div&gt;\n  &lt;div class=&quot;TS-item TS-item_color_&lt;%= card.get(&quot;topcolor&quot;) %&gt;&quot; data-timestamp=&quot;&lt;%= card.get(&quot;timestamp&quot;) %&gt;&quot;&gt;\n    &lt;div class=&quot;TS-item_label&quot;&gt;\n      &lt;% if (!_.isEmpty(card.get(&quot;html&quot;))){ %&gt;\n        &lt;div class=&quot;TS-item_user_html&quot;&gt;\n          &lt;%= card.get(&quot;html&quot;) %&gt;\n        &lt;/div&gt;\n      &lt;% } %&gt;\n      &lt;%= card.get(&quot;description&quot;) %&gt;\n    &lt;/div&gt;\n      &lt;% if (!_.isEmpty(card.get(&quot;link&quot;))){ %&gt;\n          &lt;a class=&quot;TS-read_btn&quot; target=&quot;_blank&quot; href=&quot;&lt;%= card.get(&quot;link&quot;) %&gt;&quot;&gt;Read More&lt;/a&gt;\n      &lt;% } %&gt;\n\n    &lt;div class=&quot;TS-item_year&quot;&gt;\n      &lt;span class=&quot;TS-item_year_text&quot;&gt;&lt;%= (card.get(&quot;display_date&quot;) || &quot;&quot;).length &gt; 0 ? card.get(&quot;display_date&quot;) : card.get(&quot;date&quot;) %&gt;&lt;/span&gt;\n      &lt;div class=&quot;TS-permalink&quot;&gt;&amp;#8734;&lt;/div&gt;\n    &lt;/div&gt;\n  &lt;/div&gt;\n&lt;/div&gt;&#39;</span><span class="p">);</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="p">.</span><span class="nx">notch</span><span class="o">=</span><span class="nx">a</span><span class="p">(</span><span class="s1">&#39;&lt;div class=&quot;TS-notch TS-notch_&lt;%= timestamp %&gt; TS-notch_&lt;%= series.replace(/W/g, &quot;&quot;) %&gt; TS-notch_color_&lt;%= topcolor %&gt;&quot;&gt;&lt;/div&gt;\n&#39;</span><span class="p">);</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="p">.</span><span class="nx">series_legend</span><span class="o">=</span><span class="nx">a</span><span class="p">(</span><span class="s1">&#39;&lt;div class=&quot;TS-series_legend_item TS-series_legend_item_&lt;%= name.replace(/W/g, &quot;&quot;) %&gt;&quot;&gt;\n  &lt;span class=&quot;TS-series_legend_swatch TS-series_legend_swatch_&lt;%= color %&gt;&quot;&gt;&amp;nbsp;&lt;/span&gt; &lt;span class=&quot;TS-series_legend_text&quot;&gt;&lt;%= name %&gt;&lt;/span&gt;\n&lt;/div&gt;\n&#39;</span><span class="p">);</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="p">.</span><span class="nx">timeline</span><span class="o">=</span><span class="nx">a</span><span class="p">(</span><span class="s1">&#39;&lt;div class=&quot;timeline_setter&quot;&gt;\n  &lt;div class=&quot;TS-top_matter_container&quot;&gt;\n    &lt;div class=&quot;TS-controls&quot;&gt;\n      &lt;a href=&quot;#&quot; class=&quot;TS-zoom TS-zoom_in&quot;&gt;&lt;span class=&quot;TS-controls_inner_text TS-zoom_inner_text&quot;&gt;+&lt;/span&gt;&lt;/a&gt; \n      &lt;a href=&quot;#&quot; class=&quot;TS-zoom TS-zoom_out&quot;&gt;&lt;span class=&quot;TS-controls_inner_text TS-zoom_inner_text&quot;&gt;-&lt;/span&gt;&lt;/a&gt; \n        &amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp; \n      &lt;a href=&quot;#&quot; class=&quot;TS-choose TS-choose_prev&quot;&gt;&amp;laquo;&amp;nbsp;&lt;span class=&quot;TS-controls_inner_text&quot;&gt;Previous&lt;/span&gt;&lt;/a&gt; \n      &lt;a href=&quot;#&quot; class=&quot;TS-choose TS-choose_next&quot;&gt;&lt;span class=&quot;TS-controls_inner_text&quot;&gt;Next&lt;/span&gt;&amp;nbsp;&amp;raquo;&lt;/a&gt;\n    &lt;/div&gt;\n    &lt;div class=&quot;TS-series_nav_container&quot;&gt;&lt;/div&gt;\n  &lt;/div&gt;\n\n  &lt;div class=&quot;TS-notchbar_container&quot;&gt;\n    &lt;div class=&quot;TS-notchbar&quot;&gt;&lt;/div&gt;\n  &lt;/div&gt;\n  &lt;div class=&quot;TS-card_scroller&quot;&gt;\n    &lt;div class=&quot;TS-card_scroller_inner&quot;&gt;\n    &lt;/div&gt;\n  &lt;/div&gt;\n&lt;/div&gt;&#39;</span><span class="p">);</span><span class="nb">window</span><span class="p">.</span><span class="nx">JST</span><span class="p">.</span><span class="nx">year_notch</span><span class="o">=</span><span class="nx">a</span><span class="p">(</span><span class="s1">&#39;&lt;div class=&quot;TS-year_notch TS-year_notch_&lt;%= timestamp %&gt;&quot;&gt;\n  &lt;span class=&quot;TS-year_notch_year_text&quot;&gt;&lt;%= human %&gt;&lt;/span&gt;\n&lt;/div&gt;\n&#39;</span><span class="p">)})();</span>
+
+</pre></div>             </td>           </tr>                </tbody>     </table>   </div> </body> </html>