generator-politico-embeds

A Yeoman generator to scaffold a development environment for building POLITICO embeddable interactives.

What it does:

• Scaffolds your project's development directory.
• Compiles SCSS and bundles JS written in either ES5 or ES2015 using your choice of browserify or webpack.
• Creates responsive image sets optimized for mobile devices.
• Publishes your project to an Amazon S3 bucket.

What you'll need installed

Make sure you have node installed as well as the yarn package manager.

Then install gulp, yeoman and this generator, globally*:

$ npm install -g gulp-cli yo generator-politico-embeds

* You may need to prefix with sudo

How to use

Starting a new project

Create a fresh directory for your project and move into it in your console.

$ mkdir my-project
$ cd my-project

Now run the generator and answer the questions it asks to build your dev environment.

$ yo politico-embeds

Run gulp to start the development server.

$ gulp

Develop files in the src directory and they will be automatically compiled to the dist directory, which are the files that will actually be published.

When you're ready to publish, complete the share information in meta.json, then run the publish command through gulp.

$ gulp publish

If you need to invalidate files you've previously published in CloudFront, add the --invalidate flag to the publish command:

$ gulp publish --invalidate

Restarting a project

1. Clone the project from github and cd into the project folder.
2. Install dependencies:

   $ yarn install

3. If your project is using ArchieML, run gulp archie to reconfigure :

   $ gulp archie

4. Start gulp!

Working with templates

Templates are rendered using Nunjucks templating syntax. See Nunjucks' template inheritance, tags and builtin filters for more information.

Put data in templates/data.json and it will be rendered as context with your templates. For example:

// templates/data.json
{
  "headline": "My headline"
}

<!-- A template -->
<h1>{{headline}}</h1>

There is also an extra filter specifically for rendering Markdown:

<!-- Render context data with markdown -->
{{someText|markdown}}
<!-- Remove the outer paragraph tags with strip option -->
<h1>{{sectionTitle|markdown(strip=true)}}</h1>

ArchieML

Optionally, there is a gulp task available which allows you to use ArchieML and Google Docs to render content into your templates.

You will be asked if you want to use ArchieML when you start the generator. You can also add it to a project later by running:

$ yo politico-interactives:archie

To setup the ArchieML task you will need API credentials from a project in the Google Developers Console. Ask a developer for the client ID and secret keys. You will also need to provide the ID for the Google doc you wish to use, which you can get from the URL of your doc:

https://docs.google.com/document/d/yourgoogleIDhere/edit

These credentials are put into archie.json, which you can change at any time.

Your document must have access set to "Anyone with the link can view" to use this task.

The archie gulp task will access your Google doc and overwrite templates/data.json with ArchieML data. To run it:

$ gulp archie

On first running the task, you will need to authorize access to the document through Google. The task will open the authorization dialogue in your browser. Follow the prompts and then copy and paste the code returned in the redirect URL, which will look like this in the URL bar:

http://localhost:6006/?code=COPY-THIS-CODE-HERE

This access token will be saved in google-token.json so that you can run the task subsequently without needing to re-authorize.

Note: If you've added ArchieML after the project was already created, you'll also need to add the task to your gulpfile. Simply edit it into the array of other tasks in gulpfile.js:

const gulp = require('./gulp')([
  'aws',
  'archie', // Add this line
  // ...
]);