Boilerplate for Creating Data Viz on newamerica.org

Setup

Install our data visualization project generator: npm i -g @newamerica/na-cli. Then run: na-cli setup YOUR-PROJECT-SLUG -d path/to/install/directory. That's it!

Alternatively, you can set up a project manually:

Run git clone https://github.com/newamerica-graphics/data-viz-boilerplate.git.

Before starting to build, run npm install and change the git origin git remote set-url origin https://github.com/newamerica-graphics/REPOSITORY.git, after creating a new repo in the newamerica-graphics organization.

Change the name of the project in package.json to your repository's name. This will be the name of the directory the project is deployed to on s3 (see deploy.sh). Make sure the name of the repository in github is the same as this project slug, because the github repo will be linked to from data.newamerica.org. The convention for project names is program initials, project slug: epp_polling_dashboard.

Once you've scaffolded/cloned the boilerplate:

1. Define all chartIDs that will be referenced in wagtail inside webpack.config.js
2. Build your graphic any way you like
3. Inside src/index.js define initialization functions for each graphic. It may look something like this:

var settings = {
  "id-for-chart1": chart1init,
  "id-for-chart2": chart2init
};

window.renderDataViz = function(el) {
  let id = el.getAttribute(id);
  if (settings[id]) settings[id](el);
};

newamericadotorg looks for any element with the class .na-dataviz, and if a renderDataViz function is defined globally, calls it for each element. You can see a mock of what happens in the index.html file.

Charts, Maps, and UI Components

Teddy is a library of charts, maps, and user interface components we've built to support New America's data viz work. These are no longer included by default in the boilerplate, but can be installed through npm (alternatively, the na-cli utility can also install these packages for you). Teddy is mostly built with React and a low-level data visualization library called vx. While you don't have to use React or vx to build a graphic, we find that it speeds up development considerably, and using our predefined components enforces visual styles across all data viz projects.

Deployment

• Make sure you have the AWS CLI configured properly on your machine. If you have Homebrew installed, run brew update && brew install awscli and then aws configure and finally aws configure set preview.cloudfront true
• Make sure you have renamed your project in package.json.
• Run npm run deploy
• All deployments are cached by AWS cloudfront and available at https://data.newamerica.org/ and on s3 here.

Notes

• React, ReactDOM, ReactRedux, and Redux are all globally scoped on newamerica.org, and defined as externals within this repo's webpack config. There is no need to install or bundle those dependencies if the graphic will exist exclusively on newamerica.org.

• Critical styles from newamerica.org are included in the head. This includes all fonts and type styles, bootstrap columns, margins, and containers.