tutorial/introduction.html

<!doctype>
<head>
	<link rel="stylesheet" href="vendor/prettify/prettify.css">
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script>
	<script src="vendor/prettify/prettify.js"></script>
	<link rel="stylesheet" href="style.css">
</head>

<body>

<h1>Taking Rickshaw for a Go</h1>

<p>
Rickshaw is a simple framework for drawing charts of time series data
on a web page, built on top of Mike Bostock's delightful 
<a href="http://mbostock.github.com/d3/">D3 library</a>.  These charts 
can be powered by static historical data sets, or living data that 
continuously updates in real time.
</p>

<p>
Rickshaw builds on top of D3 technically, and spiritually too.
Rickshaw makes every effort to provide help for common problems
without obscuring anything underneath it.  If you need to reach down
to D3 or the SVG layers below, go right ahead -- it's all there waiting.
</p>

<p>
Let's start with a simple but complete program that paints a chart:
</p>

<section class="example" id="example_01">
	<header>
		<a href="example_01.html" target="_blank">view</a>
		<h3>Example 01</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint"></pre>
</section>

<p>
Breaking that down, first we pull in our dependencies and create
a div to hold our chart.  Then in our <code>script</code> we
call <code>Rickshaw.Graph</code>'s constructor, and pass along an
element reference to our chart container, some layout instructions,
and a series of data objects.
</p>

<p>
The <code>series</code> object has a couple of slots,
a <code>data</code> array of coordinate objects, and a color to draw
them with. Finally, we call the render() method on our just instantiated
graph object, which creates paints our chart on the screen.
</p>

<h2>Let's Try with Real Data</h2>

<p>
Our previous work allowed us to paint a chart of made up values with
minimal scaffolding.  That was fun, but it doesn't tell us anything
interesting about data.  Let's use <a href="http://2010.census.gov/2010census/data/pop_change.csv">population change data</a> from the
2010 U.S. Census to power our chart, and see what we find.
</p>

<p>
We'll begin by drawing a line representing the United States
population with a point for each decade from 1910 to 2010.  We'll use
a short <a href="transform.pl">script</a> we've written to massage the
CSV data at the census.gov URL into a JavaScript data structure
that <code>Rickshaw.Graph</code>'s constructor can take as
its <code>data</code> argument.
</p>

<br>
<section class="example" id="example_02">
	<header>
		<a href="example_02.html" target="_blank">view</a>
		<h3>Example 02</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint linenums"></pre>
</section>

<h2>Time on the X-Axis</h2>

<p>
A trained eye can already see some points of interest there.  For
instance, ending about a quarter way into the graph there is a short
period where the growth rate flattens out significantly.  What
happened then?
</p>

<p>
First we have to answer the question of when the flattening happened.
Putting a label on our x axis should help.  Rickshaw gives us a helper
for time based axes.  After we modify our data transformation script
to use epoch seconds for the <code>x</code> values we can pass our
graph along to <code>Rickshaw.Graph.Axis.Time</code>'s constructor.
When the graph's <code>render()</code> function is later called
Rickshaw examines the <code>x</code> domain and determines the time
unit being used, and labels the graph accordingly.  The styling we
included lines up the labels nicely across the bottom of our graph.
</p>

<p>
Our updated <a href="./transform_epoch.pl">transform_epoch.pl</a> uses epoch 
seconds for <code>x</code>.  Let's see how we do.
</p>

<br>
<section class="example" id="example_03">
	<header>
		<a href="example_03.html" target="_blank">view</a>
		<h3>Example 03</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint linenums"></pre>
</section>


<h2>Y-Axis Too</h2>

<p>
Now let's add the pieces to get a <code>y</code> axis.  We need a new
HTML element to put the <code>y</code> axis in, as well as some
styling to position the axis absolutely in relation to the chart.
</p>

<p>
We pass along a reference to our graph to
<code>Rickshaw.Graph.Axis.Y</code>'s constructor, as well as the
element we want to draw the axis inside.  We also ask
<code>Rickshaw.Fixtures.Number.formatKMBT</code> to help us format the
numbers on our <code>y</code> ticks in there.
</p>

<section class="example" id="example_04">
	<header>
		<a href="example_04.html" target="_blank">view</a>
		<h3>Example 04</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint linenums"></pre>
</section>
<br>

<h2>Breaking Things Down</h2>

<p>
The Great Depression left a mark.  We should break that data down by 
region.  Some simple changes to our data transformation gives us the 
regional data for our series.  Here's <a href="transform_region.pl">transform_region.pl</a>.
</p>

<p>
Plugging that data into our series parameter leaves us wanting to
provide colors for each of those individual series.  We'll use the
<code>Rickshaw.Color.Palette</code> plugin to pick our colors.  Once
we've created our palette, calling its <code>color()</code> method
returns the next color.
</p>

<br>
<section class="example" id="example_05">
	<header>
		<a href="example_05.html" target="_blank">view</a>
		<h3>Example 05</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint linenums"></pre>
</section>

<h2>What Are We Looking At?</h2>

<p>
We need a legend!  Following a familiar pattern, we add a container
div for the legend and style it.  Then we call the constructor for the
<code>Rickshaw.Graph.Legend</code> plugin, which takes a reference to
our newly added DOM element, and a reference to the graph.
</p>

<br>
<section class="example" id="example_06">
	<header>
		<a href="example_06.html" target="_blank">view</a>
		<h3>Example 06</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint linenums"></pre>
</section>

<h2>Unstacking</h2>

<p>
It's clear that the South is growing quickly, but instead of painting
this chart as a stacked graph it would be nice to see how these growth
patterns line up against each other.  We set the renderer in a
callback, and then ask the graph to update.
</p>
<p>
In addition to setting the default renderer for the graph, we've added
a little JavaScript to observe clicks between our stack/line toggle
whose job is to update the type of renderer we're using and render the
graph appropriately.
</p>

<br>
<section class="example" id="example_07">
	<header>
		<a href="example_07.html" target="_blank">view</a>
		<h3>Example 07</h3>
	</header>
	<iframe scrolling="no"></iframe>
	<pre class="prettyprint"></pre>
</section>

<h2>More Later</h2>

<p>
We're just getting started, but that's all for today.  Next time we'll
get into stacked bars, and different line interpolations, and smoothing,
and zooming.
</p>

<p>
If you're clamoring for more, you may enjoy a poke around in the 
<a href="../examples/">examples</a> directory.
</p>

<br><br>
<script>
var sections = document.querySelectorAll('section.example');

var htmlEntities = function(str) {
	return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
}

Array.prototype.forEach.call(sections, function(s) {

	var code = s.querySelector('pre');
	var iframe = s.querySelector('iframe');
	var anchor = s.querySelector('a');

	var exampleURL = s.getAttribute('id') + ".html";

	iframe.src = exampleURL;

	$.ajax( {
		url: exampleURL,
		success: function(r) {
			code.innerHTML = htmlEntities(r);
			code.innerHTML = prettyPrintOne(code.innerHTML);
		}
	} );

} );

</script>
</body>