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]!)
nprapps' Project Template
- About this template
- Assumptions
- What's in here?
- Install requirements
- Project secrets
- Adding a template/view
- Run the project locally
- Editing workflow
- Run Javascript tests
- Run Python tests
- Compile static assets
- Test the rendered app
- Deploy to S3
- Install web services
About this template
This template provides a a project skeleton suitable for any project that is to be served entirely as flat files. Facilities are provided for rendering html from data, compiling LESS into CSS, deploying to S3, installing cron jobs on servers, copy-editing via Google Spreadsheets and a whole raft of other stuff.
Please note: This project is not intended to be a generic solution. We strongly encourage those who love the app-template to use it as a basis for their own project template. We have no plans to remove NPR-specific code from this project.
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.
What's in here?
The project contains the following folders and important files:
confs-- Server configuration files for nginx and uwsgi. Edit the templates thenfab <ENV> render_confs, don't edit anything inconfs/rendereddirectly.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 workflowcrontab-- 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 teenage-diaries
npm install
mkvirtualenv teenage-diaries
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
templatesdirectory. 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
.htmland do not start with_will automatically be rendered when you callfab 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 teenage-diaries
python app.py
Visit localhost:8000 in your browser.
Editing workflow
IMPORTANT NOTE: Google Spreadsheets now serves up XLSX files, not the XLS file that this project expects. For now, the connection has been disabled (see the update_copy function in fabfile.py), and the project instead pulls from a spreadsheet stored in data/copy.xls.
The app is rigged up to Google Docs for a simple key/value store that provides an editing workflow.
- If there is a column called
key, there is expected to be a column calledvalueand 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.
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 teenage-diaries
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
Install web services
Web services are configured in the confs/ folder. Currently, there are two: nginx.conf and uwsgi.conf.
Running fab setup will deploy your confs if you have set env.deploy_to_servers and env.deploy_web_services both to True at the top of fabfile.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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent