• Stars
    star
    151
  • Rank 246,057 (Top 5 %)
  • Language
    JavaScript
  • License
    Other
  • Created about 11 years ago
  • Updated about 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Planet Money Makes A T-Shirt

Copyright 2013 NPR. All rights reserved. No part of these materials may be reproduced, modified, stored in a retrieval system, or retransmitted, in any form or by any means, electronic, mechanical or otherwise, without prior written permission from NPR.

(Want to use this code? Send an email to [email protected]!)

tshirt

What is this?

NPR's Planet Money wanted to see the hidden world behind clothes sold in this country, so they decided to make a T-shirt. They wanted to make an ordinary shirt like the vast majority of the shirts sold in this country — not organic cotton, not hand-sewn in the United States.

See the live app — combining video, text, photos and graphics — here: http://apps.npr.org/tshirt/

This is a single-page app, using the following key libraries:

Assumptions

The following things are assumed to be true in this documentation.

  • You are running OSX.
  • You are using Python 2.7. (Probably the version that came OSX.)
  • You have virtualenv and virtualenvwrapper installed and working.

For more details on the technology stack used with the app-template, see our development environment blog post.

What's in here?

The project contains the following folders and important files:

  • confs -- Server configuration files for nginx and uwsgi. Edit the templates then fab <ENV> render_confs, don't edit anything in confs/rendered directly.
  • data -- Data files, such as those used to generate HTML.
  • etc -- Miscellaneous scripts and metadata for project bootstrapping.
  • jst -- Javascript (Underscore.js) templates.
  • less -- LESS files, will be compiled to CSS and concatenated for deployment.
  • templates -- HTML (Jinja2) templates, to be compiled locally.
  • tests -- Python unit tests.
  • www -- Static and compiled assets to be deployed. (a.k.a. "the output")
  • www/live-data -- "Live" data deployed to S3 via cron jobs or other mechanisms. (Not deployed with the rest of the project.)
  • www/test -- Javascript tests and supporting files.
  • app.py -- A Flask app for rendering the project locally.
  • app_config.py -- Global project configuration for scripts, deployment, etc.
  • copytext.py -- Code supporting the Editing workflow
  • crontab -- Cron jobs to be installed as part of the project.
  • fabfile.py -- Fabric commands automating setup and deployment.
  • public_app.py -- A Flask app for running server-side code.
  • render_utils.py -- Code supporting template rendering.
  • requirements.txt -- Python requirements.

Install requirements

Node.js is required for the static asset pipeline. If you don't already have it, get it like this:

brew install node
curl https://npmjs.org/install.sh | sh

Then install the project requirements:

cd tshirt
npm install less universal-jst -g --prefix node_modules
mkvirtualenv --no-site-packages tshirt
pip install -r requirements.txt

Project secrets

Project secrets should never be stored in app_config.py or anywhere else in the repository. They will be leaked to the client if you do. Instead, always store passwords, keys, etc. in environment variables and document that they are needed here in the README.

Adding a template/view

A site can have any number of rendered templates (i.e. pages). Each will need a corresponding view. To create a new one:

  • Add a template to the templates directory. Ensure it extends _base.html.
  • Add a corresponding view function to app.py. Decorate it with a route to the page name, i.e. @app.route('/filename.html')
  • By convention only views that end with .html and do not start with _ will automatically be rendered when you call fab render.

Run the project locally

A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.

workon tshirt
python app.py

Visit localhost:8000 in your browser.

Editing workflow

The app is rigged up to Google Docs for a simple key/value store that provides an editing workflow.

View the sample copy spreadsheet here. A few things to note:

  • If there is a column called key, there is expected to be a column called value and rows will be accessed in templates as key/value pairs
  • Rows may also be accessed in templates by row index using iterators (see below)
  • You may have any number of worksheets
  • This document must be "published to the web" using Google Docs' interface

This document is specified in app_config with the variable COPY_GOOGLE_DOC_KEY. To use your own spreadsheet, change this value to reflect your document's key (found in the Google Docs URL after &key=).

The app template is outfitted with a few fab utility functions that make pulling changes and updating your local data easy.

To update the latest document, simply run:

fab update_copy

Note: update_copy runs automatically whenever fab render is called.

At the template level, Jinja maintains a COPY object that you can use to access your values in the templates. Using our example sheet, to use the byline key in templates/index.html:

{{ COPY.attribution.byline }}

More generally, you can access anything defined in your Google Doc like so:

{{ COPY.sheet_name.key_name }}

You may also access rows using iterators. In this case, the column headers of the spreadsheet become keys and the row cells values. For example:

{% for row in COPY.sheet_name %}
{{ row.column_one_header }}
{{ row.column_two_header }}
{% endfor %}

Run Javascript tests

With the project running, visit localhost:8000/test/SpecRunner.html.

Run Python tests

Python unit tests are stored in the tests directory. Run them with fab tests.

Compile static assets

Compile LESS to CSS, compile javascript templates to Javascript and minify all assets:

workon tshirt
fab render

(This is done automatically whenever you deploy to S3.)

Test the rendered app

If you want to test the app once you've rendered it out, just use the Python webserver:

cd www
python -m SimpleHTTPServer

Deploy to S3

fab staging master deploy

Deploy to EC2

You can deploy to EC2 for a variety of reasons. We cover two cases: Running a dynamic web application (public_app.py) and executing cron jobs (crontab).

Servers capable of running the app can be setup using our servers project.

For running a Web application:

  • In app_config.py set DEPLOY_TO_SERVERS to True.
  • Also in app_config.py set DEPLOY_WEB_SERVICES to True.
  • Run fab staging master setup_server to configure the server.
  • Run fab staging master deploy to deploy the app.

For running cron jobs:

  • In app_config.py set DEPLOY_TO_SERVERS to True.
  • Also in app_config.py, set INSTALL_CRONTAB to True
  • Run fab staging master setup_server to configure the server.
  • Run fab staging master deploy to deploy the app.

You can configure your EC2 instance to both run Web services and execute cron jobs; just set both environment variables in the fabfile.

Install cron jobs

Cron jobs are defined in the file crontab. Each task should use the cron.sh shim to ensure the project's virtualenv is properly activated prior to execution. For example:

* * * * * ubuntu bash /home/ubuntu/apps/$PROJECT_NAME/repository/cron.sh fab $DEPLOYMENT_TARGET cron_test

Note: In this example you will need to replace $PROJECT_NAME with your actual deployed project name.

To install your crontab set INSTALL_CRONTAB to True in app_config.py. Cron jobs will be automatically installed each time you deploy to EC2.

Install web services

Web services are configured in the confs/ folder.

Running fab setup_server will deploy your confs if you have set DEPLOY_TO_SERVERS and DEPLOY_WEB_SERVICES both to True at the top of app_config.py.

To check that these files are being properly rendered, you can render them locally and see the results in the confs/rendered/ directory.

fab render_confs

You can also deploy the configuration files independently of the setup command by running:

fab deploy_confs

Run a remote fab command

Sometimes it makes sense to run a fabric command on the server, for instance, when you need to render using a production database. You can do this with the fabcast fabric command. For example:

fab staging master fabcast:deploy

If any of the commands you run themselves require executing on the server, the server will SSH into itself to run them.

More Repositories

1

app-template

The NPR visuals team's opinionated project template for client-side apps.
JavaScript
1,536
star
2

bestpractices

Best practices and coding conventions for the NPR Visuals team.
286
star
3

dailygraphics

NPR Visuals' rig for deploying daily graphics projects in responsive iframes.
JavaScript
285
star
4

copytext

A library for accessing a spreadsheet as a native Python object suitable for templating.
Python
225
star
5

lunchbox

Image tools for social media sharing
JavaScript
173
star
6

mapturner

A command line utility for generating topojson from various data sources for fast maps.
Python
110
star
7

quotable

REPO DEPRECATED; see the current version in Lunchbox http://github.com/nprapps/lunchbox
JavaScript
93
star
8

nprapps.github.com

The NPR visuals team's blog.
HTML
77
star
9

interactive-template

A Node-based template for starting news apps and interactive pages
JavaScript
55
star
10

newscast.js

A library to radically simplify Chromecast web app development.
JavaScript
54
star
11

dailygraphics-next

NPR's daily graphics rig, 2.0
JavaScript
43
star
12

heat-income

Analysis of heat and income in U.S. cities
Python
34
star
13

book-concierge

A concierge for every year
Less
33
star
14

armslist-scraper

A simple scraper for armslist.com listings
Python
32
star
15

waterbug

REPO DEPRECATED; see the current version in Lunchbox http://github.com/nprapps/lunchbox
JavaScript
29
star
16

sidechain

Modern responsive iframes
JavaScript
29
star
17

roku-tinydesk

Tiny Desk Concerts Roku app
Brightscript
28
star
18

books13

NPR's Book Concierge: Our Guide To 2013's Great Reads
JavaScript
27
star
19

totebot2

Everything is better in the new building, even the totebot.
CoffeeScript
25
star
20

django-starter-kit

Opinionated template for Django projects on Python 3 and PostgreSQL
Python
24
star
21

lookatthis

Stories about how you see the world.
JavaScript
22
star
22

betty

An unambiguous dialect of ArchieML
JavaScript
20
star
23

trump-tweet-analysis

Data and sentiment analysis of Trump's tweets
Jupyter Notebook
20
star
24

anno-docs

Live transcription rig
JavaScript
19
star
25

graphics-archive

Archived graphics published using our dailygraphics rig
JavaScript
16
star
26

worldvalues

World Values Survey data analysis
Python
15
star
27

elections16

App for 2016 primary elections
JavaScript
15
star
28

carebot

NPR Visual's Carebot (deprecated, now in: https://github.com/thecarebot/carebot)
Python
15
star
29

walmart

Mapping the growth of Wal-Mart in urban areas.
Shell
14
star
30

ucr-clearance-parser

parse uniform crime reporting clearance data
Python
13
star
31

envivo

A live-blogging application.
Python
13
star
32

bestsongs14

Songs We Love 2014
JavaScript
13
star
33

electris

Elections 2012
PLpgSQL
13
star
34

copydoc

Like copytext, but for docs
HTML
12
star
35

papertrail

Rig for deploying DocumentCloud viewers to S3.
JavaScript
12
star
36

tumble

A rig for handling static tumblr themes in a reasonable fashion.
CSS
12
star
37

playgrounds2

A community-edited guide to accessible playgrounds in the United States.
JavaScript
11
star
38

elections14

We're having an election party.
JavaScript
11
star
39

barkedu

The world is starting to forget about Ebola. The village of Barkedu can't.
JavaScript
10
star
40

dailygraphics-templates

Graphic templates for the dailygraphics-next rig
JavaScript
9
star
41

stl-lobbying

Lobbying in Missouri project with SLPR
JavaScript
9
star
42

bernard

Python
9
star
43

servers

Server setup scripts for NPR Apps servers.
Shell
9
star
44

hollerith

Publish Sheets to S3 as JSON
JavaScript
8
star
45

leso

Processing scripts for Defense Logistics Agency LESO data
Shell
8
star
46

books14

NPR's Book Concierge app
JavaScript
8
star
47

photo-finder

An internal-facing tool for searching instagram.
JavaScript
8
star
48

arrested-development

The one about Arrested Development.
JavaScript
8
star
49

us-wildfires

Fire-forecast data for the United States.
JavaScript
8
star
50

ap-election-loader

basic AP election loader
Shell
8
star
51

elections20-interactive

Front-end graphics for the 2020 general election
JavaScript
8
star
52

mental-health

A Silent Epidemic: The Mental Health Crisis In Our Schools
JavaScript
8
star
53

elections20-primaries

Primary results for 2020
JavaScript
7
star
54

borders-map

Borderland collaboration with CIR
JavaScript
7
star
55

cron-starter-kit

This is a simple starter kit for deploying and maintaining cron jobs on EC2 servers.
Python
7
star
56

austin

The Austin 100
JavaScript
7
star
57

shelf-life

A Tumblr rig for pantry raids.
JavaScript
7
star
58

school-choice

Data analysis for education's school choice in Indiana project
Jupyter Notebook
6
star
59

elections22

Data pipeline and results graphics for the 2022 general election. Building off elections20-interactive.
JavaScript
6
star
60

nprchat

Experimental chat using Firebase.
JavaScript
6
star
61

armslist-analysis

Analysis of the armslist dataset
Python
6
star
62

liveblog-standalone

NPR's liveblog rig 2.0
JavaScript
6
star
63

inauguration

NPR Inauguration 2013 live chat (built on Scribble Live) and "Dear Mr. President" listener call-out (built on Tumblr)
JavaScript
6
star
64

wolves

Big beautiful Gilkey photos of wolves & Nate Rott's audio opus
JavaScript
6
star
65

civilrights

Behind The Civil Rights Act: How it was made and what it means today—commentary on the landmark Civil Rights Act of 1964.
JavaScript
6
star
66

congress-bot

Bot to track legislation and other activity by members of Congress from a specific state
Python
5
star
67

graeae

JavaScript
5
star
68

books18

Best books of 2018
JavaScript
5
star
69

books16

book concierge 2016 edition
JavaScript
5
star
70

elections18-graphics

2018 midterm election front-end; iteration upon 2016 GE work
JavaScript
5
star
71

oscars

Oscar Night 2013 live chat / liveblog (built on Scribble Live), and Best Picture cheat sheet
JavaScript
5
star
72

anno-lambda-authorizer

AWS lambda function that serves as a custom authorizer for AWS API Gateway
Python
5
star
73

geocode-nominatim

Geocode structured & unstructured addresses using Nominatim service
Python
4
star
74

cypher

A Vagrant config for running NPR's news apps
4
star
75

clerk

A cron job --> Slack webhook that posts new action from the House floor
Python
4
star
76

pym-particle

Active development moved to Sidechain
JavaScript
4
star
77

ahca

Python
4
star
78

rockymountain

JavaScript
4
star
79

in-memoriam-2013

NPR Music remembers the singers, instrumentalists, songwriters and personalities who died in 2013.
JavaScript
4
star
80

disability

HTML breakout story page for the Planet Money / This American Life / NPR project "Unfit For Work."
JavaScript
4
star
81

executive-orders

Cron job that posts to Slack incoming webhook when new executive orders (or actions or memos) are published to whitehouse.gov
Python
4
star
82

nola

The End Of Neighborhood Schools: New Orleans charter schools
JavaScript
3
star
83

autocomplete-input

JavaScript
3
star
84

sanctuary-cities

Python
3
star
85

bestsongs15-midyear

best songz, 2015 midyear edition
JavaScript
3
star
86

commencement

The Best Commencement Speeches, Ever
JavaScript
3
star
87

sea-level-scroll

Visual narrative: Who Will Pay To Protect Tech Giants From Rising Seas?
JavaScript
3
star
88

okkervil

An audio-guided tour through a Leaflet map
JavaScript
3
star
89

syria

With Syria engulfed in civil war, here are four stories of families struggling to stay together.
JavaScript
3
star
90

elections18-general

2018 midterm election back-end: Associated Press data ETL, database, admin panel, and JSON output; iteration upon 2016 GE work
JavaScript
3
star
91

science-of-joy

It's a joy generator
JavaScript
3
star
92

factcheck-db

Python
3
star
93

sotu

Application for aggregating NPR's State of the Union coverage (built on Scribble Live)
JavaScript
3
star
94

elections16-general

You already know what it is.
JavaScript
2
star
95

musicgame

JavaScript
2
star
96

elections16graphics

Front-end for 2016 elections
JavaScript
2
star
97

wildfire-scroll

Visual narrative: United States of Wildfire
JavaScript
2
star
98

us-drought

JavaScript
2
star
99

liveblog-headlines

RSS widget for liveblogs or NPR.org API feeds
JavaScript
2
star
100

familymeal

An NPR project (built on Tumblr) centered around user-submitted photos of their dinners.
JavaScript
2
star