Building with Tarbell¶
This tutorial will walk you through the process of building a simple news application and publishing it on the web. You will learn the basics of responsive design and charting with D3 by visualizing data by the @chitowncoders Cook County Jail scraper.
You will get hands-on experience in every stage of the development process: working with data, sketching mockups, writing HTML, CSS, and Javascript and recording your work using Git’s version control system.
You will learn to use Backbone JS to structure your application, Underscore JS to process data, Twitter Bootstrap to structure your markup, and D3 for data visualization. The techniques used here were first described in Responsive Charts with D3 and Backbone by Ryan Nagle.
This guide was prepared for Migrahack Mexico City, April 3-6, 2014 and presented by David Eads.
- Code repository: https://github.com/sc3/26thycalifornia
- Demonstration: http://26thycalifornia.recoveredfactory.net
- Documentation: http://migrahack.readthedocs.org/
- Issues: https://github.com/sc3/26thycalifornia/issues
Prerequisites¶
- A modern web browser (Chrome or Chromium)
- A text editor to work with plain text files
- A command-line interface to interact with your computer
- Git version control software
- (Optional) An account at GitHub.com
Web browser¶
Firefox or Chrome.
Text editor¶
You’ll be editing simple “plain text” files.
Just like you need a word processor for writing human language, you need a text editor for working with plain text such as HTML markup, CSS, and Javascript.
Sublime Text is highly recommended. It’s fast, simple, and runs on all major platforms.
Command-line interface¶
Every computer should be a way to open a window that lets you type in commands. Different operating systems give this tool slightly different names, but they all have some form of it, and there are alternative programs you can install as well.
On Windows you can find the command-line interface by opening the “command prompt.” Here are instructions for Windows 8 and earlier versions.
On Apple computers, you open the “Terminal” application.
Ubuntu Linux comes with a program of the same name.
Git and GitHub¶
Git is a version control program for saving the changes you make to files over time. This is useful when you’re working on your own, but quickly becomes essential with large software projects, especially if you work with other developers.
GitHub is a website that hosts git code repositories, both public and private. It comes with many helpful tools for reviewing code and managing projects. It also has some extra tricks that make it easy to publish web pages, which we will use later.
GitHub offers helpful guides for installing Git in Windows, Macs and Linux. You can verify it’s installed from your command line like so:
# You don't have to type the "$" It's just a generic symbol
# geeks use to show they're working on the command line.
$ git --version
Once that’s done, you should create an account at GitHub, if you don’t already have one. It shouldn’t cost you anything. The free plan is all that’s required to complete this lesson.
Planning: Know your data¶
- Acquire meaningful data (the data for this tutorial comes from a scraper).
- Question the data: - Does the data need cleaning or scrubbing? - What comparisons can be made? - How can the data be bucketed or categorized? - How can the data be normalized and averaged?
- Process data: “Boil down” into useful summary data structures. - Time series - Ratios - Distributions
- Publish raw and summarized data with a web API
Time summaries of crime incident data by David Eads describes how the the Chicago Tribune applies these techniques to crime data.
Planning: Sketch your interface¶
Todo (need photos of sketches)
Set up: Bootstrap your project¶
Note
Don’t care about the nitty gritty details of setting up your project? Not running OS X or Linux? Just skip ahead to the next chapter.
Project setup details