Copyright 2014 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!)
- What is this?
- Assumptions
- What's in here?
- Bootstrap the project
- Hide project secrets
- Save media assets
- Add a page to the site
- Run the project
- Developing posts
- Starting a new post
- Working on an existing post
- Turning on extra features
- Deploying a post
- Deleting posts
- COPY editing
- Arbitrary Google Docs
- Run Python tests
- Run Javascript tests
- Compile static assets
- Test the rendered app
- Deploy to S3
- Deploy to EC2
- Install cron jobs
- Install web services
- Run a remote fab command
- Report analytics
- Updating sitemap
Look At This contains all of the stories built for lookatthisstory.tumblr.com as well as the Tumblr theme. It contains a basic post template and tooling for creating, editing and deploying a new post.
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.
- You have NPR's AWS credentials stored as environment variables locally.
For more details on the technology stack used with the app-template, see our development environment blog post.
The project contains the following folders and important files:
data-- Data files, such as those used to generate HTML.fabfile-- Fabric commands for automating setup, deployment, data processing, etc.etc-- Miscellaneous scripts and metadata for project bootstrapping.new-post-- The default new post template.posts-- Where Look At This posts liveposts/$SLUG/templates/slides-- Slide templates for a particular postposts/%SLUG/less/slides--.lessfiles for post slide templatestemplates-- HTML (Jinja2) templates, to be compiled locally.app.py-- A Flask app for rendering the project locally.app_config.py-- Global project configuration for scripts, deployment, etc.render_utils.py-- Code supporting template rendering.requirements.txt-- Python requirements.static.py-- Static Flask views used in bothapp.pyandpublic_app.py.static_post.py-- Helper Flask views for compiling postsstatic_post.py-- Helper Flask views for compiling Tumblr theme
Node.js is required for the static asset pipeline. If you don't already have it, get it like this:
brew install node
curl -L https://npmjs.org/install.sh | sh
Then bootstrap the project:
cd lookatthis
mkvirtualenv lookatthis
pip install -r requirements.txt
npm install
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.
The required environment variables for this project are in the # lookatthis section of env.sh in the workinprivate repo. You will need to copy and paste those lines to your ~/.bash_profile.
Large media assets (images, videos, audio) are synced with an Amazon S3 bucket specified in app_config.ASSETS_S3_BUCKET in a folder with the name of the project. (This bucket should not be the same as any of your app_config.PRODUCTION_S3_BUCKETS or app_config.STAGING_S3_BUCKETS.) This allows everyone who works on the project to access these assets without storing them in the repo, giving us faster clone times and the ability to open source our work.
Syncing these assets requires running a couple different commands at the right times. When you create new assets or make changes to current assets that need to get uploaded to the server, run fab post:$SLUG assets.sync. This will do a few things:
- If there is an asset on S3 that does not exist on your local filesystem it will be downloaded.
- If there is an asset on that exists on your local filesystem but not on S3, you will be prompted to either upload (type "u") OR delete (type "d") your local copy.
- You can also upload all local files (type "la") or delete all local files (type "da"). Type "c" to cancel if you aren't sure what to do.
- If both you and the server have an asset and they are the same, it will be skipped.
- If both you and the server have an asset and they are different, you will be prompted to take either the remote version (type "r") or the local version (type "l").
- You can also take all remote versions (type "ra") or all local versions (type "la"). Type "c" to cancel if you aren't sure what to do.
Unfortunantely, there is no automatic way to know when a file has been intentionally deleted from the server or your local directory. When you want to simultaneously remove a file from the server and your local environment (i.e. it is not needed in the project any longer), run fab post:$SLUG assets.rm:"file_name_here.jpg"
A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.
workon $PROJECT_SLUG
fab app
Visit localhost:8000 in your browser.
Working with posts on the command line revolves around the fab post:$SLUG command. All commands that follow fab post:$SLUG will work with just the post specified.
Run fab post:$SLUG. This function will ask you to create a new post and place it in the posts folder. It will also create a spreadsheet for you and give you the URL to that spreadsheet in the terminal.
If you are working on a post that already exists in the repo for the first time, be sure to run fab post:$SLUG update to get the assets and copytext spreadsheet.
The default COPY document has several sheets. You will create new slides in the content sheet. Each slide is one row in this sheet. Each row includes:
id: a unique ID for the slide (see below for guidelines)template: the name of the slide templatetext1,text2,text3: fields for the various pieces of text your template requires (see below for guidelines)foreground_media: image that your template will use in the foreground of the slide, such as a side-by-side (not required)background_media: image that your template will use as the background image (not required)caption_and_credit: Caption for the photo and creditextra_class: An extra class for style changes that don't require a change in the markup. Examples includedark-overlayandblur-background.preload_image: In the imgLiquid container for the background image, embed the src of the image in the baked page (i.e. don't lazy load). Basically, this is so Google News and other web crawlers can pick up an image.
You may use <em> and <strong> in any of the text fields, when appropriate. You should avoid using <h1> or other context-specific tags.
Each slide requires a unique ID, defined in the id column of the content spreadsheet. Each ID should use good slug style: all lowercase, descriptive of the content and uses dashes between words. For example:
-
Bad:
slide1,slide2,slide3 -
Good: names that describe the content on the page.
-
Bad:
To The Border,toTheBorder,totheborder -
Good:
to-the-border
Each slideshow comes with these default templates.
conclusion: Promo for corresponding NPR story and share buttons.framed-text: A framed box of text in the center of the screen in front of a background image.full-bleed: A bottom bar of text in front of a background image.next-post: A slide that should be used at the end of a post to promote the share panel and the next post.side-by-side: An image (on the left) next to a block of text (on the right).slide: A default slide with no special styles.start: A titlecard that includes Look At This branding, author and date.titlecard: A slide for dividing sections of a post, includes title and subtitle.
| template | text_1 | text_2 | text_3 | foreground_image |
|---|---|---|---|---|
| conclusion | Promo other NPR content | Credits | N/A | N/A |
| framed-text | Text to frame. Require <p> tags. | N/A | N/A | N/A |
| full-bleed | Text to go at the bottom of slide. Requires <p> tags. | N/A | N/A | N/A |
| next-post | The title of the next post | Caption | Link to next post | N/A |
| side-by-side | Text to go next to image | N/A | N/A | Image filename |
| slide | Text to go in the center of slide. Requires <p> tags. | N/A | N/A | N/A |
| start | Title | Subtitle | Text for begin button | N/A |
| titlecard | Title | Subtitle | N/A | N/A |
New templates should be created when the content requires a slide with a different markup structure than any of the existing templates.
To create a new template, follow these steps:
- Go into the
postsrepo on your local machine, find the post you are working on, and navigate to thetemplatesfolder. - In the
slidesfolder, create a new.htmlfile with the name of your template, i.e.essay.html - Navigate back to the root of your post, and go to the
lessfolder. - In the
slidesfolder, create a new.lessfile with the name of your template, i.e.essay.less - Finally, in
app.less, add an import line that imports your new.lessfile, i.e.@import "./slides/essay.less".
You can now use this template in the template column of your content spreadsheet.
If a slide needs style adjustments but not a new markup structure, use the id of the slide to make adjustments in CSS. Open the nudges.less file in your post's less directory to make these adjustments. For example:
#to-the-border {
p {
font-size: 20px;
}
}
Images in the foreground_media and background_media columns in the spreadsheet
are automatically lazy loaded for you.
To add images that are lazy-loaded yourself, you will need to use some special markup:
<img class="lazy-load" data-src="myimage.jpg" alt="I'm being lazy" />
Note that myimage.jpg is relative to the assets directory.
The default new post template only includes commonly used icon fonts for performance. To use all of FontAwesome, uncomment the @import statement in app.less and comment out the custom font. You'll also need to comment out and uncomment the next and previous control arrow button rules later in app.less.
Each post template comes with the code necessary to handle audio, video and filmstrips, but it is not turned on by default. To enable these features, set the appropriate variables to True in post_config.py.
When deploying a post, make sure the deploy slug is what you want it to be. The slug defaults to the name of the folder, but can be overridden in posts/$SLUG/post_config.py. Define the variable DEPLOY_SLUG to what you want the published slug to be.
Also, make sure that the variable NUM_SLIDES_AFTER_CONTENT is equal to the number of slides after the last piece of story content. For example, if there is a share slide and an up next slide, the number should be 2. This is important for tracking completion rates in our analytics.
Deploy posts with the following command:
fab post:$SLUG staging deploy
This function will deploy the static assets to S3, and can be found at stage-apps.npr.org/lookatthis/posts/$SLUG.
If you want to delete a post, use the following command:
fab post:$SLUG delete
Do not specify a deployment target. This will also delete all assets related to the post in the assets rig.
This app uses a Google Spreadsheet for a simple key/value store that provides an editing workflow.
View the sample copy spreadsheet.
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=).
A few things to note:
- 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
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 post:$SLUG text.update
Note: text.update 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 %}
When naming keys in the COPY document, pleaseattempt to group them by common prefixes and order them by appearance on the page. For instance:
title
byline
about_header
about_body
about_url
download_label
download_url
Compile LESS to CSS, compile javascript templates to Javascript and minify all assets:
workon lookatthis
fab post:$SLUG render
(This is done automatically whenever you deploy to S3.)
The Google Analytics events tracked in this application are:
| Category | Action | Label | Value | Custom 1 | Custom 2 |
|---|---|---|---|---|---|
| $POST_SLUG | tweet | location |
|||
| $POST_SLUG | location |
||||
| $POST_SLUG | location |
||||
| $POST_SLUG | new-comment | ||||
| $POST_SLUG | open-share-discuss | ||||
| $POST_SLUG | close-share-discuss | ||||
| $POST_SLUG | summary-copied | ||||
| $POST_SLUG | featured-tweet-action | action |
tweet_url |
||
| $POST_SLUG | featured-facebook-action | action |
post_url |
||
| $POST_SLUG | slide-exit | slideIndex |
timeOnSlide |
||
| $POST_SLUG | keyboard-nav | ||||
| $POST_SLUG | next-post | ||||
| $POST_SLUG | completion | percent |
(Not posts necessarily track all metrics.)
To add a project to the sitemap:
- Add a line to
data/sitemap.csv - Run ``fab staging|production sitemap