quotable

NOTE: The Quotable repository has been deprecated for our suite of social tools, Lunchbox. You can find the most recent version of Quotable over there.

• What is this?
• Assumptions
• What's in here?
• Install requirements
• Project secrets
• Adding a template/view
• Run the project locally
• Handling static assets
• Editing workflow
• Run Javascript tests
• Run Python tests
• Compile static assets
• Test the rendered app
• Deploy

What is this?

Quotable is an app that lets you make sharable images out of quotations.

This code is open source under the MIT license. See LICENSE for complete details.

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.

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:

• 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 workflow
• fabfile.py -- Fabric commands automating setup and deployment.
• 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 quotable
npm install less universal-jst -g --prefix node_modules
mkvirtualenv --no-site-packages quotable
pip install -r requirements.txt
fab update_copy

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 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 call fab 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 quotable
python app.py

Visit localhost:8000 in your browser.

Handling static assets

Make an s3 bucket for your static assets. Update ASSETS_S3_BUCKET in app_config.py with the new location. This should be separate from the s3 bucket where you are deploying your app.

Static assets should be stored in www/assets. To push new assets to the server, run fab assets_up. To pull existing assets down, run fab assets_down. To delete an asset, run fab assets_rm:'www/assets/FILE_NAME_OR_UNIX_GLOB'.

For example, if you are starting from scratch, you would copy assets into the www/assets folder and then run fab assets_up. If you are working on this project with someone who has already created assets, and you would like to get them, run fab assets_down. And if you would like to delete all JPEG files in the folder www/assets, run fab assets_rm:'www/assets/*.jpg'.

Editing workflow

The app is rigged up to Google Docs for a simple key/value store that provides an editing workflow.

View the sample copy spreadsheet here. A few things to note:

• If there is a column called key, there is expected to be a column called value and 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. To use your own spreadsheet, change this value to reflect your document's key (found in the Google Docs URL after &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 quotable
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

fab deploy