nprapps/ethics-monitor-share-pages

Name: ethics-monitor-share-pages

Owner: NPR visuals team

Description: null

Created: 2017-04-24 15:56:11.0

Updated: 2017-04-24 15:56:23.0

Pushed: 2017-05-24 21:02:47.0

Homepage: null

Size: 520

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Copyright 2017 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!)

ethics-monitor-share-pages

What is this?

Deploys redirect share pages for the Trump Ethics Monitor.

The social images live here in the assets rig. The Adobe Illustrator file used to create the social images can be found on Titan at Design/staff_files/katiepark/trump-ethics-monitor/social-cards.ai

Assumptions

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

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:

Bootstrap the project

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

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

Then bootstrap the project:

thics-monitor-share-pages
rtualenv ethics-monitor-share-pages
install -r requirements.txt
install
update

Problems installing requirements? You may need to run the pip command as ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install -r requirements.txt to work around an issue with OSX.

Hide 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.

Any environment variable that starts with $PROJECT_SLUG_ will be automatically loaded when app_config.get_secrets() is called.

Save media assets

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 assets.sync`. This will do a few things:

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 assets.rm:"www/assets/file_name_here.jpg"`

Adding a page to the site

A site can have any number of rendered pages, each with a corresponding template and view. To create a new one:

Run the project

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

on $PROJECT_SLUG
app

Visit localhost:8000 in your browser.

COPY configuration

This app uses a Google Spreadsheet for a simple key/value store that provides an editing workflow.

To access the Google doc, you'll need to create a Google API project via the Google developer console.

Enable the Drive API for your project and create a “web application” client ID.

For the redirect URIs use:

For the Javascript origins use:

You'll also need to set some environment variables:

rt GOOGLE_OAUTH_CLIENT_ID="something-something.apps.googleusercontent.com"
rt GOOGLE_OAUTH_CONSUMER_SECRET="bIgLonGStringOfCharacT3rs"
rt AUTHOMATIC_SALT="jAmOnYourKeyBoaRd"

Note that AUTHOMATIC_SALT can be set to any random string. It's just cryptographic salt for the authentication library we use.

Once set up, run fab app and visit http://localhost:8000 in your browser. If authentication is not configured, you'll be asked to allow the application for read-only access to Google drive, the account profile, and offline access on behalf of one of your Google accounts. This should be a one-time operation across all app-template projects.

It is possible to grant access to other accounts on a per-project basis by changing GOOGLE_OAUTH_CREDENTIALS_PATH in app_config.py.

COPY editing

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. (The long string of random looking characters in your Google Docs URL. For example: 1DiE0j6vcCm55Dyj_sV5OJYoNXRRhn_Pjsndba7dVljo)

A few things to note:

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:

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:

OPY.attribution.byline }}

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

OPY.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:

or row in COPY.sheet_name %}
ow.column_one_header }}
ow.column_two_header }}
ndfor %}

When naming keys in the COPY document, please attempt to group them by common prefixes and order them by appearance on the page. For instance:

e
ne
t_header
t_body
t_url
load_label
load_url
Open Linked Google Spreadsheet

Want to edit/view the app's linked google spreadsheet, we got you covered.

We have created a simple Fabric task `spreadsheet`. It will try to find and open the app's linked google spreadsheet on your default browser.

spreadsheet

If you are working with other arbitraty google docs that are not involved with the COPY rig you can pass a key as a parameter to have that spreadsheet opened instead on your browser

spreadsheet:$GOOGLE_DOC_KEY

For example:

spreadsheet:12_F0yhsXEPN1w3GOlQB4_NKGadXiRLOa9l-HQu5jSL8
ill open 270 project number-crunching spreadsheet
Generating custom font

This project uses a custom font build powered by Fontello If the font does not exist, it will be created when running fab update. To force generation of the custom font, run:

utils.install_font:true

Editing the font is a little tricky – you have to use the Fontello web gui. To open the gui with your font configuration, run:

utils.open_font

Now edit the font, download the font pack, copy the new config.json into this project's fontello directory, and run fab utils.install_font:true again.

Arbitrary Google Docs

Sometimes, our projects need to read data from a Google Doc that's not involved with the COPY rig. In this case, we've got a helper function for you to download an arbitrary Google spreadsheet.

This solution will download the uncached version of the document, unlike those methods which use the “publish to the Web” functionality baked into Google Docs. Published versions can take up to 15 minutes up update!

Make sure you're authenticated, then call oauth.get_document(key, file_path).

Here's an example of what you might do:

 copytext import Copy
 oauth import get_document

read_my_google_doc():
file_path = 'data/extra_data.xlsx'
get_document('1inbod_7Yf0hOZCGuYsO6MqLgsxW4uFxo1W0F0cIzHIY', file_path)
data = Copy(file_path)

for row in data['example_list']:
    print '%s: %s' % (row['term'], row['definition'])

_my_google_doc()
Run Python tests

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

Run Javascript tests

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

Compile static assets

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

on ethics-monitor-share-pages
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:

ww
on -m SimpleHTTPServer
Deploy to S3
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:

For running cron jobs:

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/ethics_monitor_share_pages/repository/cron.sh fab $DEPLOYMENT_TARGET cron_jobs.test

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.

The cron jobs themselves should be defined in fabfile/cron_jobs.py whenever possible.

Install web services

Web services are configured in the confs/ folder.

Running fab servers.setup 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.

servers.render_confs

You can also deploy only configuration files by running (normally this is invoked by deploy):

servers.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:

staging master servers.fabcast:deploy

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

Analytics

The Google Analytics events tracked in this application are:

|Category|Action|Label|Value| |——–|——|—–|—–| |ethics-monitor-share-pages|tweet|location|| |ethics-monitor-share-pages|facebook|location|| |ethics-monitor-share-pages|email|location|| |ethics-monitor-share-pages|new-comment|| |ethics-monitor-share-pages|open-share-discuss|| |ethics-monitor-share-pages|close-share-discuss|| |ethics-monitor-share-pages|summary-copied|| |ethics-monitor-share-pages|featured-tweet-action|action| |ethics-monitor-share-pages|featured-facebook-action|action|

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.