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 nprapps@npr.org!)
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, etc.
The project contains the following folders and important files:
data
-- Data files, such as those used to generate HTMLetc
-- Miscellaneous scripts and metadata for project bootstrapping.jst
-- Javascript (Underscore.js) templatesless
-- LESS files, will be compiled to CSS and concatenated for deploymenttemplates
-- HTML (Jinja2) templates, to be compiled locallywww
-- Static and compiled assets to be deployed (a.k.a. "the output")app.py
-- A Flask app for rendering the project locally.app_config.py
-- Global project configuration for scripts, deployment, etc.fabfile.py
-- Fabric commands automating setup and deployment
git clone git@github.com:nprapps/app-template.git $NEW_PROJECT_NAME
cd $NEW_PROJECT_NAME
rm -rf .git
git init
git add *
git add .gitignore
git commit -am "Initial import from app-template."
git remote add origin git@github.com:nprapps/$NEW_PROJECT_NAME.git
git push -u origin master
- Update
app_config.py
with the name of the new project.
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 $NEW_PROJECT_NAME
npm install less universal-jst
mkvirtualenv $NEW_PROJECT_NAME
pip install -r requirements.txt
The app-template can automatically setup your Github repo with our default labels and tickets.
- Run
fab bootstrap_issues
and enter your Github username and password.
The app-template ships with several example templates and corresponding views.
- Choose from the available templates which one to base your project on, e.g.
templates/table.html
. Move this template totemplates/index.html
and delete the others. - Never edit
www/index.html
or other dynamically generated assets. Instead edit the templates. - Choose the view from
app.py
that matches your chosen index template. Rename it toindex
, apply the@app.route('/')
decorator to it and delete the others. - Uncomment and update the ad code and Facebook tags at the top of
templates/_base.html
. (or make yourself a ticket to do it later).
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 callfab render
.
A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.
workon $NEW_PROJECT_NAME
python app.py
Visit localhost:8000
in your browser.
Compile LESS to CSS, compile javascript templates to Javascript and minify all assets:
workon $NEW_PROJECT_NAME
fab render
(This is done automatically whenever you deploy to S3.)
If you want to test the app once you've rendered it out, just use the Python webserver:
cd www
python -m SimpleHTTPServer
fab staging master deploy
The current configuration is for running cron jobs only. Web server configuration is not included.
- In
fabfile.py
setenv.deploy_to_servers
toTrue
. - Run
fab staging master setup
to configure the server. - Run
fab staging master deploy
to deploy the app.