search

nprapps / elections18-graphics

2018 midterm election front-end; iteration upon 2016 GE work
MIT License
5 stars 1 forks source link

readme

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

Elections 2018 Graphics

What is this?

Contains code for all graphics related to the 2018 General Election results.

This is a graphical summary of how each component interacts, between the three repositories involved in the experience:

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

Bootstrap the project using:

cd elections18-graphics
mkvirtualenv elections18-graphics --python="$(which python2)"
pip install -r requirements.txt
npm install
fab text.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 graphic

Run fab add_graphic:slug.

This will generate:

And trigger the webpack build once to generate the necessary rendered files.

Notes on editing the javascript and the markup

Elements hidden based on context

Certain elements of components are hidden based on what host the graphic is loaded by (specifically, member station websites vs NPR.org). On member stations, the top-level navigation bar is hidden, to prevent users from being taken away from the member station websites. On NPR.org, the NPR footer is hidden, since it's redunant with the main NPR.org footer.

Managing Javascript Dependencies

To manage JS dependencies, we use npm. To install a new JS library that will be used in client-side code, run npm install --save name-of-library. Then, in the JS file for the particular graphic you are developing, use ES6 imports to get the library in your file; for example, to import superagent and make it available as request:

import request from 'superagent';

// yr graphic

request.get(URL)
    .set('If-Modified-Since', lastRequestTime)
    .end(function(err, res) {
        // callback code
    });

If you need to add libraries to the build process (webpack, babel, etc.), you install the same way except you use npm install --save-dev name-of-library.

Run the project

A flask app is used to run the project locally. It will automatically recompile templates and assets on demand. This command also turns webpack into watch mode.

workon $PROJECT_SLUG
fab app

Visit localhost:8000 in your browser.

To load the project using a different port, run fab app:$PORT_NUMBER (for example fab app:1111). (You might want to do this if you're already using port 8000 locally for anther project and need to switch between them.)

iTerm2 shortcut

If you use iTerm2 as your terminal app, you can use this AppleScript to launch this in a two-paned terminal window. The right pane runs the webserver. The left pane lets you do your command line work. You can make an alias to launch this in your ~/.bash_profile:

alias elexgfx="osascript ~/src/elections18-graphics/etc/iterm_elections18graphics.scpt"

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:

export GOOGLE_OAUTH_CLIENT_ID="something-something.apps.googleusercontent.com"
export GOOGLE_OAUTH_CONSUMER_SECRET="bIgLonGStringOfCharacT3rs"
export 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:

fab 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, please attempt 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

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.

fab 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

fab spreadsheet:$GOOGLE_DOC_KEY

For example:

fab spreadsheet:12_F0yhsXEPN1w3GOlQB4_NKGadXiRLOa9l-HQu5jSL8
// Will 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:

fab 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:

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

Compile static assets

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

workon elections18-graphics
fab render

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

Deploy to S3

fab staging master deploy

Analytics

The Google Analytics events tracked in this application are:

Category Action Label Value
elections18-graphics switch-state-tab ${which view selected}-via-${element used to navigate}
elections18-graphics county-sort-click metric
elections18-graphics finished-graphic embed slug