@data-visuals/create 7.2.0 → 7.4.1

package/README.md

@@ -36,16 +36,16 @@ npm start
 - [Usage](#usage)
 - [Development and testing](#development-and-testing)
 - [Folder structure](#folder-structure)
-    - [config/](#config)
-    - [data/](#data)
-    - [workspace/](#workspace)
-    - [project.config.js](#projectconfigjs)
-    - [app/](#app)
-    - [app/index.html, app/static.html](#appindexhtml-appstatichtml)
-    - [app/templates/](#apptemplates)
-    - [app/scripts/](#appscripts)
-    - [app/styles/](#appstyles)
-    - [app/assets/](#appassets)
+  - [config/](#config)
+  - [data/](#data)
+  - [workspace/](#workspace)
+  - [project.config.js](#projectconfigjs)
+  - [app/](#app)
+  - [app/index.html, app/static.html](#appindexhtml-appstatichtml)
+  - [app/templates/](#apptemplates)
+  - [app/scripts/](#appscripts)
+  - [app/styles/](#appstyles)
+  - [app/assets/](#appassets)
   - [Other directories you may see](#other-directories-you-may-see)
     - [.tmp/](#tmp)
     - [dist/](#dist)
@@ -57,13 +57,13 @@ npm start
   - [Creating a new entrypoint](#creating-a-new-entrypoint)
   - [Connecting an entrypoint to an HTML file](#connecting-an-entrypoint-to-an-html-file)
 - [Available commands](#available-commands)
-    - [`npm start` or `npm run serve`](#npm-start-or-npm-run-serve)
-    - [`npm run deploy`](#npm-run-deploy)
-    - [`npm run data:fetch`](#npm-run-datafetch)
-    - [`npm run assets:push`](#npm-run-assetspush)
-    - [`npm run assets:pull`](#npm-run-assetspull)
-    - [`npm run workspace:push`](#npm-run-workspacepush)
-    - [`npm run workspace:pull`](#npm-run-workspacepull)
+  - [`npm start` or `npm run serve`](#npm-start-or-npm-run-serve)
+  - [`npm run deploy`](#npm-run-deploy)
+  - [`npm run data:fetch`](#npm-run-datafetch)
+  - [`npm run assets:push`](#npm-run-assetspush)
+  - [`npm run assets:pull`](#npm-run-assetspull)
+  - [`npm run workspace:push`](#npm-run-workspacepush)
+  - [`npm run workspace:pull`](#npm-run-workspacepull)
 - [Environment variables and authentication](#environment-variables-and-authentication)
   - [AWS](#aws)
   - [Google](#google)
@@ -87,13 +87,18 @@ npm install -g @data-visuals/create
 npx @data-visuals/create@latest <project-type> <project-name>
 ```
 
-Currently there are two project types available — `graphic` and `feature`. The project name should be passed in as a slug, i.e. `my-beautiful-project`.
+Currently there are two project types available — `graphic` and `feature`.
+
+`graphic` - embeddable graphics, like the [district race lookup embedded in this voter guide](https://www.texastribune.org/2022/01/17/texas-primary-election-2022-voter-guide/)
+`features` - entire page projects, like this [2022 primary ballot page](https://apps.texastribune.org/features/2022/texas-election-results-2022-primary/)
+
+The project name should be passed in as a slug, i.e. `my-beautiful-project`.
 
 ```sh
 npx @data-visuals/create@latest graphic school-funding
 ```
 
-This will create a directory for you, copy in the files, install the dependencies, and do your first `git commit`.
+This will create a directory for you, copy in the files, install the dependencies and do your first `git commit`.
 
 The directory name will be formatted like this:
 
@@ -106,10 +111,6 @@ graphic-school-funding-2018-01
 
 This is to ensure consistent naming of our directories!
 
-## Development and testing
-
-If you make changes locally to `@data-visuals/create` and want to test them, you can run `data-visuals-create/bin/data-visuals-create <project-type> <project-name>` to generate a graphic or feature and see if your changes were included. Run the command one level above this repo, or you'll create a graphic or feature within `data-visuals-create`.
-
 ## Folder structure
 
 After creation, your project directory should look something like this:
@@ -147,23 +148,37 @@ The `workspace` directory is for storing all of your analysis, production and ra
 
 #### project.config.js
 
-Where all the configuration for a project belongs. This is where you can change the S3 deploy parameters, manage the Google Drive documents that sync with this project, set up a bespoke API or add custom filters to Nunjucks.
+Where all the configuration for a project belongs. This is where you can change the S3 deploy parameters, manage the Google Drive documents that sync with this project, format data pulled from Google Drive documents, set up a bespoke API or add custom filters to Nunjucks.
+
+- `dataMutators` - Modify what's returned by the data fetch. This is a good place to restructure raw data, or to do joins with other data you may have. [Here's an example from our coronavirus tracker.](https://github.com/texastribune/feature-tx-coronavirus-tracker-2020-03/blob/master/project.config.js#L188)
+- `createAPI` - Bake out a series of JSON files that get deployed with your project. This is a great way to partition data that users only need a small slice of based on how they interact with our project. The kit expects this to return an array of objects. Each object should have a "key" and a "value" - the "key" determines the URL, the "value" is what is saved at that URL. [Here's an example from our voter guide.](https://github.com/texastribune/newsapps-dailies/blob/master/2022/graphic-voter-guide-primaries-2022-01/project.config.js#L136)
+- `customFilters` - Where custom filters for Nunjucks are added. Each key should be the name of the filter, and each value should be a function it will call. (journalize comes built in and does not need to be added manually.) [Here's an example from our voter guide.](https://github.com/texastribune/newsapps-dailies/blob/master/2022/graphic-voter-guide-primaries-2022-01/project.config.js#L405)
 
 #### app/
 
 Where you'll spend most of your time! Here are where all the assets that go into building your project live.
 
-#### app/index.html, app/static.html
+#### app/index.html
 
-The starter HTML pages provided by the kit. `index.html` is for scripted graphics that require additional JavaScript, and `static.html` is for graphics that do not, like Illustrator embeds. Feel free to rename them!
+This is the landing page for graphics and features. For features, this page provides a full-page template to start from. For embeddable graphics, this page has instructions on how to create embeddable graphics and which templates in `app/templates/` to clone.
 
-If your project is only a single page (or graphic), you can pick one of them where you do all your HTML work. No special configuration is required to create new HTML files - just creating a new `.html` file in in the `app` directory (but _not_ within `app/scripts/` or `/app/templates/` - HTML files have special meanings in those directories) is enough to tell the kit about new pages it should compile.
+#### app/templates/
 
-When embedding graphics other than `index.html`, remember to add the name of the template to the end of the embed link. The default link points to `index`.
+Where all the Nunjucks templates (including the `base.html` template that `app/index.html` inherits from), `includes` and `macros` live.
 
-#### app/templates/
+### Embeddable graphics
 
-Where all the Nunjucks templates (including the `base.html` template that `app/index.html` inherits from), includes and macros live.
+- `base.html` - base template used across all graphics
+- `graphic-static.html` - template for static graphics, like Illustrator embeds
+- `graphic.html` - template for graphics using JS, like ones that require D3
+
+### Features
+
+- `base.html` - base template used across all features
+- `base-embed.html` - base template used across all embeddable graphics associated with the feature
+- `embed.html` - template for embeddable graphics associated with the feature
+
+If your project is only a single page (or graphic), you can pick one of them where you do all your HTML work. No special configuration is required to create new HTML files - just creating a new `.html` file in in the `app` directory (but _not_ within `app/scripts/` or `/app/templates/` - HTML files have special meanings in those directories) is enough to tell the kit about new pages it should compile.
 
 #### app/scripts/
 
@@ -231,7 +246,7 @@ ArchieML Google Docs work as documented on the [ArchieML](http://archieml.org/)
 
 Our kit can display variables pulled in from Google Docs in the template. This is helpful when we want to show data in our text that is in the `data/` folder. Nunjucks finds the variable syntax (anything in curly braces) in our Google Doc text and displays the corresponding value.
 
-By default, Nunjucks has access to every file in our `data/` folder as an object. For example, if there are two files in the `data/` folder named `data.json` and `text.json` respectively, it will be structured as: 
+By default, Nunjucks has access to every file in our `data/` folder as an object. For example, if there are two files in the `data/` folder named `data.json` and `text.json` respectively, it will be structured as:
 
 ```json
 {
@@ -291,7 +306,7 @@ touch app/scripts/packs/maps.js
 
 Because there's a lot more going on behind the scenes than just adding a `<script>` tag, you have to set a special variable in a template in order to get the right entrypoint into the right HTML file.
 
-Set `jsPackName` anywhere in the HTML file to the name of your entrypoint (__without__ the extension) to route the right JavaScript files to it.
+Set `jsPackName` anywhere in the HTML file to the name of your entrypoint (**without** the extension) to route the right JavaScript files to it.
 
 ```html
 {% set jsPackName = 'map' %}
@@ -312,6 +327,14 @@ The main command for development. This will build your HTML pages, prepare your
 
 The main command for deployment. It will always run `npm run build` first to ensure the compiled version is up-to-date. Use this when you want to put your project online. This will use the `bucket` and `folder` values in the `project.config.js` file to determine where it should be deployed on S3. Make sure those are set the appropriate values!
 
+#### `npm run build`
+
+The main command for compiling files. Stores compiled files in the `dist/` folder. Also runs `npm run parse` which parses project for metadata.
+
+#### `npm run parse`
+
+The main command for parsing metadata from projects. Refer to `project-metadata.md` for more information.
+
 #### `npm run data:fetch`
 
 This command uses the array of files listed under the `files` key in `project.config.js` to download data to the project. This data will be processed and made available in the `data` folder in the root of the project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-visuals/create",
-  "version": "7.2.0",
+  "version": "7.4.1",
   "description": "Create graphics and features the Data Visuals way.",
   "scripts": {
     "build:docs": "doctoc README.md --github",

package/templates/__common__/_package.json

@@ -17,7 +17,7 @@
     "workspace:push": "node ./utils/deployment/push-workspace.js"
   },
   "devDependencies": {
-    "@babel/core": "^7.0.0",
+    "@babel/core": "^7.17.8",
     "@babel/plugin-proposal-class-properties": "^7.1.0",
     "@babel/plugin-syntax-dynamic-import": "^7.0.0",
     "@babel/plugin-transform-react-jsx": "^7.0.0",
@@ -28,7 +28,7 @@
     "ansi-colors": "^3.2.3",
     "archieml": "^0.4.1",
     "assets-webpack-plugin": "^6.1.2",
-    "autoprefixer": "^9.0.2",
+    "autoprefixer": "^10.4.2",
     "aws-sdk": "^2.372.0",
     "babel-eslint": "^10.0.1",
     "babel-loader": "^8.0.0",
@@ -50,7 +50,7 @@
     "fast-glob": "^2.2.2",
     "fs-extra": "^7.0.0",
     "glob-watcher": "^5.0.3",
-    "googleapis": "^83.0.0",
+    "googleapis": "^99.0.0",
     "html-minifier": "^3.5.21",
     "imagemin": "^7.0.0",
     "imagemin-gifsicle": "^7.0.0",
@@ -60,7 +60,7 @@
     "journalize": "^2.1.0",
     "mime-types": "^2.1.17",
     "nunjucks": "^3.0.1",
-    "postcss": "^7.0.2",
+    "postcss": "^8.4.12",
     "postcss-flexbugs-fixes": "^4.1.0",
     "prettier": "^1.12.1",
     "puppeteer": "^5.5.0",

package/templates/__common__/app/scripts/utils/clamp.js

@@ -1,3 +1,13 @@
+/**
+ * Returns the minimum if n is less than the minimum.
+ * Returns the maximum if n is more than the maximum.
+ * Returns n if n is between the minimum and maximum.
+ *
+ * @param {Number} n
+ * @param {Number} min
+ * @param {Number} max
+ * @return {Number}
+ */
 export default function clamp(n, min, max) {
   return Math.min(Math.max(n, min), max);
 }

package/templates/__common__/app/scripts/utils/get-current-url.js

@@ -1,3 +1,8 @@
+/**
+ * Returns current URL as a String.
+ *
+ * @return {String}
+ */
 function getCurrentUrl() {
   const loc = window.location;
   return `${loc.protocol}//${loc.host}${loc.pathname}`;

package/templates/__common__/app/scripts/utils/serialize-query-string.js

@@ -7,7 +7,7 @@
 const encode = encodeURIComponent;
 
 /**
- * Converts an object of key/value pairs into a encoded query string.
+ * Converts an object of key/value pairs into an encoded query string.
  *
  * @param  {Object} params The params of the query string
  * @return {String}

package/templates/__common__/app/scripts/utils/sum-values.js

@@ -1,3 +1,10 @@
+/**
+ * Sums up values of a property across objects in an array.
+ *
+ * @param {Array} arr An array of objects.
+ * @param {String} key The property to sum across objects.
+ * @return {Number}
+ */
 export default function sumValues(arr, key) {
   return arr.reduce((acc, obj) => acc + obj[key], 0);
 }

package/templates/__common__/app/templates/macros/prose.html

@@ -1,9 +1,9 @@
 {% import 'macros/processors.html' as processors %}
 
-{% macro prose(content, context, data) %}
+{% macro prose(content, context, data, type) %}
 {% for item in content %}
   {% if processors[item.type] %}
-    {{ processors[item.type](item.value, context, data) }}
+    {{ processors[item.type](item.value, context, data, type) }}
   {% else %}
     {{ processors['raw'](item.value, context, data) }}
   {% endif %}

package/templates/__common__/config/tasks/graphics-meta.js

@@ -170,7 +170,7 @@ const parseGraphic = async (
   // create array from credits
   if (credits.length > 0) {
     // separate by commas or and
-    credits = credits.replace('Credit: ', '').split(/, *| and */g);
+    credits = credits.split(/, *| and */g);
   } else {
     credits = [];
   }
@@ -180,7 +180,15 @@ const parseGraphic = async (
     const caption = await getText({ key: 'caption', page });
     const altText = await getText({ key: 'alt-text', page });
     const note = await getText({ key: 'note', page });
-    const source = await getText({ key: 'source', page });
+    let source = await getText({ key: 'source', page });
+
+    // create array from source
+    if (source.length > 0) {
+      // separate by commas or and
+      source = source.split(/, *| and */g);
+    } else {
+      source = [];
+    }
 
     const links = await page.$$eval('a', links =>
       links.map(link => {

package/templates/__common__/project-metadata.md

@@ -0,0 +1,186 @@
+## Graphics and features metadata
+
+In order to keep track of our graphics and features, metadata is grabbed from each project when we deploy them! (Hooray!) Metadata is scraped via specific selectors present in the HTML. The values for these selectors are parsed and output into a `manifest.json` file.
+
+The metadata from `manifest.json` is then pasted into our [work log](https://docs.google.com/spreadsheets/d/1hCP5zGx8dNxk59gI9wBSFY2juJVM8OFCDY45VnNb2nI/edit#gid=965603489), which powers the CMS graphics plugin. Only embeddable graphics are present in the plugin — full-page features are not. The plugin surfaces our graphics for editors to embed them into stories.
+
+| Selector/Variable | Alt Text | Example | Output in manifest.json |
+|--|--|--|--|
+| `[data-graphic]` or `[data-feature]` | If present, the HTML of the page will be parsed for metadata and surfaced in the CMS | `<div class="app" data-graphic>` or `<main data-feature>` | N/A - If no `[data-graphic]` or `[data-feature]` selector is found, the project won't output in manifest. |
+| `{{ graphicTitle }}` or `[data-title]` | The title of the project in the CMS. **If this is missing in an embeddable graphic, the graphic will not surface in the CMS.** | `{% set  graphicTitle = 'Some title' %}` or `<h1 class="graphic-title" data-title>Some title</h1>` | `title: string` |
+| `{{ graphicAltText }}` | The alt text of the graphic in the CMS. This will also be read by screenreaders in platforms like Apple News. | `{% set graphicAltText = 'This is a bar chart showing xyz' %}` | `altText: string` |
+| `{{ graphicCaption }}` or `[data-caption]` | The caption of the graphic in the CMS. The text typically below the title. | `{% set graphicCaption = 'Summarizing statement about the values in the graphic.' %}` or `<span data-caption>{{ prose(context.prose, context, graphicData) }}</span>` | `caption: string` |
+| `{{ graphicNote }}` or `[data-note]` | Note or disclaimer attached to the graphic. | `{% set graphicNote = 'Important disclaimer about this graphic.' %}` or `<li data-note>Note: Important disclaimer about this graphic.</li>` | `note: string` |
+| `{{ graphicSource }}` or `[data-source]` | The source of the graphic in the CMS | `{% set  graphicSource = 'TXDOT' %}` or `<li data-source>Source: TXDOT</li>` | `source: string` |
+| `{{ graphicCredit }}` or `[data-credit]` | The author names for the project in the CMS. | `{% set  graphicCredit = 'Texas Tribune Staff' %}` or `<li data-credit>Texas Tribune Staff</li>`  | `credits: array` |
+| `{{ graphicTags }}` | The tags for the project in the CMS. | `{% set graphicTags = context.guten_tags %}` | `tags: array` |
+
+The metadata as a variable, i.e. `graphicTitle` and `graphicCaption`, takes precedent over metadata in selectors, i.e. `[data-title]` and `[data-caption]`.
+
+### Full example with an embeddable graphic
+
+`context` is data from the project's ArchieML Google Doc.
+
+```html
+{% extends 'base.html' %}
+{% set context = data.text %}
+{% set graphicAltText = context.alttext %}
+{% set graphicTags = context.guten_tags %}
+{% block content %}
+<div class="app" data-graphic>
+  <h1 class="graphic-title" data-title>{{ context.headline }}</h1>
+  <span data-caption>{{ prose(context.prose, context, graphicData) }}</span>
+  <div id="graphic" class="graphic"></div>
+  <ul class="graphic-footer">
+    <li data-note>Note: {{ context.note }}</li>
+    <li data-source>Source: {{ context.source }}</li>
+    <li data-credit>Credit: {{ context.credit }}</li>
+  </ul>
+</div>
+{% endblock content %}
+```
+
+### Full example with a full-page feature
+
+`context` is data from the project's ArchieML Google Doc.
+
+```html
+{% set graphicTags = context.guten_tags %}
+<main data-feature>
+  <article class="has-giant-btm-marg">
+    {% block content %}
+      <div class="has-page-padding has-giant-btm-marg">
+        <header class="t-align-center">
+          <h1 class="l-container l-container--m t-headline t-serif t-lh-s has-s-btm-marg" data-title>{{ context.headline | widont }}</h1>
+          <p class="t-byline t-links t-uppercase t-lsp-m t-size-xs has-text-gray-dark has-b-btm-marg">
+            <span class="t-byline__item">By <span data-credit>{%- for author in context.authors -%}
+            {% if not loop.last %}{{ authorComma() }}{% elif not loop.first %} and{% endif %} <span class="l-display-ib">{{ author }}</span>
+            {%- endfor -%}</span>
+            </span>
+          </p>
+        </header>
+      </div>
+    {% endblock content %}
+  </article>
+</main>
+```
+
+### Full example with ai2html graphic
+
+Sometimes in Illustrator graphics, we set the title and other info in the Illustrator file itself and not the HTML, so we'd need to add those as nunjucks variables to surface the metadata. `context` is data from the project's ArchieML Google Doc.
+
+```html
+{% extends 'base.html' %}
+{% set context = data.text %}
+{% set graphicTitle = context.headline %}
+{% set graphicCaption = context.prose %}
+{% set graphicAltText = context.alttext %}
+{% set graphicNote = context.note %}
+{% set graphicSource = context.source %}
+{% set graphicCredit = context.credit %}
+{% set graphicTags = context.guten_tags %}
+{% block content %}
+<div class="app" data-graphic>
+  <h1 class="graphic-title" data-title>{{ context.headline | widont }}</h1>
+  <span data-caption>{{ prose(context.prose, context, graphicData) }}</span>
+  {% set ai2html = "border-map-full" %}
+  {% include "ai2html-output/" + ai2html + ".html" %}
+  <ul class="graphic-footer">
+    <li data-note>Note: {{ context.note }}</li>
+    <li data-source>Source: {{ context.source }}</li>
+    <li data-credit>Credit: {{ context.credit }}</li>
+  </ul>
+</div>
+{% endblock content %}
+```
+
+### Other metadata
+
+Along with HTML selectors, we also get metadata about graphics through the `project.config.js`. These are global to the whole project.
+
+Project config keys output in `manifest.json`
+
+- `type`
+- `bucket`
+- `createMonth`
+- `createYear`
+- `lastBuildTime`
+- `folder`
+- `id`
+- `parserOptions`
+  - `appleNewsIgnore` - **Only applies to embeddable graphics** This is an array of files or folders that should be flagged in the CMS as not compatible with Apple News. Use this for graphics that are too dynamic to be accurately captured in a screenshot.
+
+### Ignoring projects
+
+If any projects should be ignored in `manifest.json`, add the paths in `metadataIgnore` in `project.config.js`.
+
+- `parserOptions`
+  - `metadataIgnore` - This is an array of files or folders that should not be parsed for metadata and displayed in the CMS graphics plugin. For example, any graphics or features created for testing but are not publishable should be added here.
+
+### Sample `manifest.json` output for embeddable graphics
+
+```json
+[
+  {
+    "type": "graphic",
+    "title": "Title of graphic",
+    "altText": "Alt text of graphic",
+    "bucket": "graphics.texastribune.org",
+    "projectPath": "graphics/new-test-2-2021-02/static",
+    "projectURL": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/",
+    "caption": "Caption of graphic",
+    "createMonth": "02",
+    "createYear": "2021",
+    "credits": ["Mandi Cai", "Darla Cameron", "Carla Astudillo", "Chris Essig"],
+    "folder": "graphics/new-test-2-2021-02",
+    "id": "uniqueString",
+    "lastBuildTime": "2021-04-22T19:28:30.269Z",
+    "label": "static/index.html",
+    "links": [
+      {
+        "url": "https://www.texastribune.org/series/news-apps-graphics-databases/",
+        "text": "See more graphics like this",
+        "isCTA": true
+      }
+    ],
+    "note": "Note: Texas Department of State Health Services was missing data last year.",
+    "previews": {
+      "large": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/preview-large.png",
+      "small": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/preview-small.png"
+    },
+    "showInAppleNews": true,
+    "source": "Source: Texas Department of State Health Services and U.S. Census ACS 2018 population estimates",
+    "tags": ["subject-politics"]
+  }
+]
+```
+
+### Sample `manifest.json` output for full-page features
+
+```json
+[
+  {
+    "type": "feature",
+    "title": "Title of the feature",
+    "bucket": "apps.texastribune.org",
+    "projectPath": "features/2022/new-test-2-2021-02",
+    "projectURL": "https://apps.texastribune.org/features/2022/new-test-2-2021-02/",
+    "createMonth": "04",
+    "createYear": "2022",
+    "credits": ["Texas Tribune Staff"],
+    "folder": "features/2022/new-test-2-2021-02",
+    "id": "uniqueString",
+    "lastBuildTime": "2022-04-21T15:49:19.130Z",
+    "label": "index.html",
+    "tags": ["subject-politics"]
+  }
+]
+```
+
+### How it works
+
+The `npm run parse` step will use [Puppeteer](https://github.com/puppeteer/puppeteer) and a local Chrome install to emulate the project in a browser. This will help build metadata based on a project's HTML and, for embeddable graphics, export image-based previews of the graphic as well as a manifest of all the metadata (`manifest.json`).
+
+#### Troubleshooting
+
+By default, this process assumes you're using MacOS. To change this for other operating systems, rerun the command with the correct install path variable: `CHROME_INSTALL_PATH="local/path/to/chrome" npm run parse`.

package/templates/__common__/utils/deployment/deploy.js

@@ -35,31 +35,4 @@ ${colors.blue.underline(mainPath)} (This has been copied to your clipboard.)
 Did you run ${colors.yellow(
     `npm run data:fetch`
   )} before deploying to get the latest data?`);
-
-  if (projectType === 'feature') {
-    console.log(`
-If you are deploying a feature, check Facebook/Twitter/other social platforms to make sure the 
-share image shows up.`);
-  }
-
-  if (projectType === 'graphic') {
-    console.log(`
-If you are deploying a graphic in a CMS story, there are a few steps. First,
-add this in the Content section of the Raw Plugin:
-${colors.yellow(
-  `<div class="dv201808-graphic dv201808-graphic--centered dv201808-graphic--centered-narrow" data-frame-src="${mainPath}" data-frame-sandbox="allow-scripts allow-same-origin allow-top-navigation-by-user-activation allow-top-navigation"></div>`
-)}`);
-
-    console.log(`
-Next, add the style code snippet found in ${colors.yellow(
-      'app/styles/raw-plugin-styles.html'
-    )} to the CSS content section of the Raw Plugin`);
-
-    console.log(`
-Then, add this line to the JavaScript content section of the Raw Plugin:
-${colors.yellow(
-  '<script src="https://cdn.texastribune.org/lib/@newswire/frames@0.3.1/index.umd.js"></script>'
-)}
-${colors.yellow('<script>newswireFrames.autoInitFrames();</script>')}`);
-  }
 });

package/templates/__common__/utils/fetch/authorize.js

@@ -79,8 +79,10 @@ async function getAuth() {
 function getGoogleToken(auth, googleTokenFile) {
   return new Promise((resolve, reject) => {
     const url = auth.generateAuthUrl({
-      access_type: 'offline',
       scope: SCOPES,
+      response_type: "code",
+      redirect_uri: auth.redirectUri,
+      client_id: auth._clientId
     });
 
     console.log(
@@ -96,10 +98,12 @@ function getGoogleToken(auth, googleTokenFile) {
     });
 
     rl.question(
-      colors.bold('Enter your success code from that page here:\n'),
-      async code => {
+      colors.bold("Sign in with your @texastribune.org account and hit 'Allow' to grant access to News Apps Graphics Kit.\nAfter you are redirected, the page will look broken, but copy the URL and paste it here:\n"),
+      async url => {
         rl.close();
 
+        const code = url.split(/[?=&]+/)[2];
+
         let tokens;
 
         try {
@@ -118,4 +122,4 @@ function getGoogleToken(auth, googleTokenFile) {
   });
 }
 
-module.exports = { getAuth };
+module.exports = { getAuth };

package/templates/feature/README.md

@@ -10,22 +10,30 @@ This is a running list of things you should do before you launch any project on
 
 Our process for pitching and executing projects (which should happen before all of this) can be found on [this doc](https://docs.google.com/document/d/1E7QE8gp29h20EAafzSui8VjQ_9TG5-XhR33tbAP0hBA/edit).
 
-## Final editing checklist
+### Final editing checklist
 Before your embedded graphic or feature goes live, here's the editing steps you need to take:
 
+#### Initial steps
 - [ ] Spell check and self-edit — does everything make sense?
-- [ ] Data visuals editor for a visual edit
-- [ ] Design feedback channel (optional for more complex graphics or apps)
 - [ ] Story reporter, if a collaboration
+
+#### Editing
+Copy editors have a deadline of 5 pm so all editing should be done early afternoon the day before publication (at the latest)
 - [ ] Story or beat editor for a line edit to check facts
-- [ ] DV team in the secret channel (for a final gut check)
-- [ ] Copy editor
+- [ ] Data visuals editor for edits and/or fact check
+- [ ] DV team in the secret channel (for a final gut check. Darla can also provide visual edits in this channel, if she's available)
+- [ ] Optional: Design feedback channel (can provide design edits)
+
+#### Final steps
+- [ ] Copy editor — their deadline is 5 p.m.
 - [ ] Be available the night before publication for any last-minute changes, or let other DV teammates know how to make edits
 
-### Headline
-- [ ] Get a headline by submitting the story's budget line to the Headline Hoedown Slack channel
+### Headline and pointer
+- [ ] If it's an apps page, we need to get the page's headline, slug and summary all approved by an editor. This is done in the team-editors channel. As of June 2022, only the Data Visuals Editor has access to that channel so they will need to hoedown this information for you. Also, it's likely you will need to hoedown a SEO headline as well for the pointer inside the CMS. These are created so a link to the apps page can show up on our website. Here's [an example](https://www.texastribune.org/admin/articles/articlelink/40354/change/) of one we've done.
 
 ### Article
+If you're creating an apps page, make sure you complete these.
+
 - [ ] Add ads (three is typically the minimum; add more if longer)
 - [ ] Make sure there's related articles (powered by the `guten_tag` property in the feature's ArchieML doc)
 - [ ] Add any sigs, icons, or lead art

package/templates/feature/app/scripts/packs/graphic-embed.js

@@ -0,0 +1,31 @@
+/* eslint-disable no-unused-vars */
+import * as d3 from 'd3';
+import createBase from '../utils/d3-base';
+
+// a reference to the default graphic container, change if needed
+const container = d3.select('#graphic');
+
+// a helper function to clear the container of its contents
+const clearContainer = () => container.html('');
+
+// a helper function to grab the container's width
+const getFrameWidth = () => container.node().offsetWidth;
+
+// import data by getting the window variable, OR by importing the filepath
+// let data = window.DATA;
+// import data from '../../../data/data.json';
+// import data from 'Data/data.json';
+
+/**
+ * This function is called to render a graphic, using d3 or a library of your choice.
+ *
+ * @return {void}
+ */
+export default function renderGraphic() {
+  // pass the recalculated frameWidth to parts of your chart (like an axis) that change with resize!
+  clearContainer();
+  const frameWidth = getFrameWidth();
+  //
+  // rest of your code goes here
+  // use createBase() to create the base of an d3 chart
+}

package/templates/feature/app/scripts/packs/main-embed.js

@@ -0,0 +1,7 @@
+import { frameLoader } from '../embeds/frames';
+import renderGraphic from './graphic-embed';
+
+// included in index.html by default
+// initiates frame so your graphic is wrapped in an AMP-compatible iframe
+// renderGraphic() renders a coded graphic on load and on resize
+frameLoader(renderGraphic);

package/templates/feature/app/scripts/utils/ad-loader.js

@@ -99,9 +99,13 @@ class AdLoader {
         adElementId
       );
 
-      // overwrites the default fixed size set above
-      // if the ad is a banner ad
-      gptAdUnit.defineSizeMapping(banner);
+      // make ad square if it includes the `dv-gpt-ad-square` class
+      if (attributes.class.includes('dv-gpt-ad-square')) {
+        gptAdUnit.defineSizeMapping([300, 250]);
+      } else {
+        // else use banner dimensions
+        gptAdUnit.defineSizeMapping(banner);
+      }
 
       if (options.targetingKey && options.targetingValue) {
         gptAdUnit.setTargeting(options.targetingKey, options.targetingValue);

package/templates/feature/app/templates/{base-graphic.html → base-embed.html}

@@ -22,8 +22,9 @@
   {% if graphicSource %}
     <meta name="tt-graphic-source" content="{{ graphicSource }}" />
   {% endif %}
-
-  <meta name="tt-graphic-credit" content="{{ graphicCredit or 'Texas Tribune Staff'}}" />
+  {% if graphicCredit %}
+    <meta name="tt-graphic-credit" content="{{ graphicCredit }}" />
+  {% endif %}
   <meta name="tt-graphic-tags" content="{{ graphicTags or ['subject-politics'] }}" />
 
   <link rel="dns-prefetch" href="https://www.google-analytics.com">

package/templates/feature/app/templates/{graphic.html → embed.html}

@@ -1,9 +1,9 @@
 {# Template for any scripted graphics, i.e. D3 charts #}
-{% extends 'base-graphic.html' %}
+{% extends 'base-embed.html' %}
 {% from 'macros/prose.html' import prose %}
 
 {# set pack that provides JS #}
-{% set jsPackName = 'main' %}
+{% set jsPackName = 'main-embed' %}
 
 {# data.text --> data/text.json #}
 {% set context = data.text %}
@@ -23,16 +23,16 @@
   {# data-title is used to grab the title in the CMS #}
   <h1 class="graphic-title" data-title>{{ context.headline | widont }}</h1>
   {# data-caption is used to grab the caption in the CMS #}
-  <span data-caption>{{ prose(context.graphic_prose, context, graphicData) }}</span>
+  <span data-caption>{{ prose(context.embed_prose, context, graphicData, 'embed') }}</span>
 
   {# container that JS is attached to #}
   <div id="graphic" class="graphic"></div>
 
   {# data-source, data-credit, and data-note are also used in the CMS #}
   <ul class="graphic-footer">
-    {% if context.note %}<li data-note>Note: {{ context.note }}</li>{% endif %}
-    {% if context.source %}<li data-source>Source: {{ context.source }}</li>{% endif %}
-    {% if context.credit %}<li data-credit>Credit: {{ context.credit }}</li>{% endif %}
+    {% if context.embed_note %}<li>Note: <span data-note>{{ context.embed_note }}</span></li>{% endif %}
+    {% if context.embed_source %}<li>Source: <span data-source>{{ context.embed_source }}</span></li>{% endif %}
+    {% if context.embed_credit %}<li>Credit: <span data-credit>{{ context.embed_credit }}</span></li>{% endif %}
   </ul>
 </div>
 {% endblock content %}

package/templates/feature/app/templates/includes/metas.html

@@ -19,7 +19,7 @@
 <meta property="og:site_name" content="The Texas Tribune">
 <meta property="og:image" content="{{ staticAbsolute('assets/images/share-art.jpg', true) }}">
 <meta property="fb:app_id" content="154122474650943">
-<meta name="parsely-title" content="{{ context.headline|escape }}" />
+<meta name="parsely-title" content="{{ context.seo_headline|escape }}" />
 <meta name="parsely-link" content="{{ CURRENT_PAGE_URL }}" />
 <meta name="parsely-type" content="post" />
 <meta name="parsely-image-url" content="{{ staticAbsolute('assets/images/share-art.jpg', true) }}" />

package/templates/feature/app/templates/macros/processors.html

@@ -4,8 +4,12 @@
 {{ value | renderStringWithNunjucks(data) }}
 {% endmacro %}
 
-{% macro text(value, context, data) %}
-<p class="copy">{{ value | renderStringWithNunjucks(data) }}</p>
+{% macro text(value, context, data, type) %}
+  {% if type == 'embed' %}
+    <p class="graphic-prose">{{ value | renderStringWithNunjucks(data) }}</p>
+  {% else %}
+    <p class="copy">{{ value | renderStringWithNunjucks(data) }}</p>
+  {% endif %}
 {% endmacro %}
 
 {% macro list(value) %}

package/templates/graphic/app/templates/base.html

@@ -22,8 +22,9 @@
   {% if graphicSource %}
     <meta name="tt-graphic-source" content="{{ graphicSource }}" />
   {% endif %}
-
-  <meta name="tt-graphic-credit" content="{{ graphicCredit or 'Texas Tribune Staff'}}" />
+  {% if graphicCredit %}
+    <meta name="tt-graphic-credit" content="{{ graphicCredit }}" />
+  {% endif %}
   <meta name="tt-graphic-tags" content="{{ graphicTags or ['subject-politics'] }}" />
 
   <link rel="dns-prefetch" href="https://www.google-analytics.com">

package/templates/graphic/app/templates/graphic-static.html

@@ -27,7 +27,7 @@
 {# data-graphic signifies that this can be embedded in the CMS #}
 <div class="app" data-graphic>
   {# data-title is used to grab the title in the CMS #}
-  <h1 class="graphic-title" data-title>{{ context.headline | widont }}</h1>
+  <h1 class="graphic-title" data-title>{{ context.headline | widont or 'The only member-supported, digital-first, nonpartisan media organization' | widont }}</h1>
   {# data-caption is used to grab the caption in the CMS #}
   <span data-caption>{{ prose(context.prose, context, graphicData) }}</span>
 
@@ -37,9 +37,9 @@
 
   {# data-source and data-credit are also used in the CMS #}
   <ul class="graphic-footer">
-    {% if context.note %}<li data-note>Note: {{ context.note }}</li>{% endif %}
-    {% if context.source %}<li data-source>Source: {{ context.source }}</li>{% endif %}
-    {% if context.credit %}<li data-credit>Credit: {{ context.credit }}</li>{% endif %}
+    {% if context.note %}<li>Note: <span data-note>{{ context.note }}</span></li>{% endif %}
+    {% if context.source %}<li>Source: <span data-source>{{ context.source }}</span></li>{% endif %}
+    {% if context.credit %}<li>Credit: <span data-credit>{{ context.credit }}</span></li>{% endif %}
   </ul>
 </div>
 {% endblock content %}

package/templates/graphic/app/templates/graphic.html

@@ -21,7 +21,7 @@
 {# data-graphic signifies that this can be embedded in the CMS #}
 <div class="app" data-graphic>
   {# data-title is used to grab the title in the CMS #}
-  <h1 class="graphic-title" data-title>{{ context.headline | widont }}</h1>
+  <h1 class="graphic-title" data-title>{{ context.headline | widont or 'The only member-supported, digital-first, nonpartisan media organization' | widont }}</h1>
   {# data-caption is used to grab the caption in the CMS #}
   <span data-caption>{{ prose(context.prose, context, graphicData) }}</span>
 
@@ -30,9 +30,9 @@
 
   {# data-source, data-credit, and data-note are also used in the CMS #}
   <ul class="graphic-footer">
-    {% if context.note %}<li data-note>Note: {{ context.note }}</li>{% endif %}
-    {% if context.source %}<li data-source>Source: {{ context.source }}</li>{% endif %}
-    {% if context.credit %}<li data-credit>Credit: {{ context.credit }}</li>{% endif %}
+    {% if context.note %}<li>Note: <span data-note>{{ context.note }}</span></li>{% endif %}
+    {% if context.source %}<li>Source: <span data-source>{{ context.source }}</span></li>{% endif %}
+    {% if context.credit %}<li>Credit: <span data-credit>{{ context.credit }}</span></li>{% endif %}
   </ul>
 </div>
 {% endblock content %}

package/templates/graphic/graphics-meta.md

@@ -1,120 +0,0 @@
-## Graphics metadata
-
-Graphics intended to be used as embeds in the CMS should have specific selectors present in the HTML. The values for these selectors are parsed and output into a `manifest.json` file which is used by the graphics plugin to organize our graphics inventory.
-
-
-| Selector/Variable | Alt Text | Example | Output in manifest.json |
-|--|--|--|--|
-| `[data-graphic]` | If present, the HTML of the page will be parsed for metadata and surfaced in the CMS | `<div class="app" data-graphic>` | N/A - If no `[data-graphic]` selector is found, the graphic won't output in manifest. |
-| `{{ graphicTitle }}` or `[data-title]` | The title of the graphic in the CMS. **If this is missing, the graphic will not surface in the CMS.** | `{% set  graphicTitle = 'Some title' %}` or `<h1 class="graphic-title" data-title>Some title</h1>` | `title: string` |
-| `{{ graphicAltText }}` | The alt text of the graphic in the CMS. This will also be read by screenreaders in platforms like Apple News. | `{% set graphicAltText = 'This is a bar chart showing xyz' %}` | `altText: string` |
-| `{{ graphicCaption }}` | The caption of the graphic in the CMS. The text typically below the title. | `{% set graphicCaption = 'Summarizing statement about the values in the graphic.' %}` | `caption: string` |
-| `{{ graphicNote }}` or `[data-note]` | Note or disclaimer attached to the graphic. | `{% set graphicNote = 'Important disclaimer about this graphic.' %}` or `<li data-note>Note: Important disclaimer about this graphic.</li>` | `note: string` |
-| `{{ graphicSource }}` or `[data-source]` | The source of the graphic in the CMS | `{% set  graphicSource = 'TXDOT' %}` or `<li data-source>Source: TXDOT</li>` | `source: string` |
-| `{{ graphicCredit }}` or `[data-credit]` | The author names for the graphic in the CMS. | `{% set  graphicCredit = 'Trib Tribington, Super Cool Corgi' %}` or `<li data-credit>Trib Tribington and Super Cool Corgi</li>`  | `credits: array` |
-
-### Full example
-```html
-{% extends 'base.html' %}
-{% set context = data.text %}
-{% set graphicAltText = 'Alt text of graphic' %}
-{% block content %}
-<div class="app" data-graphic>
-	<h1 class="graphic-title" data-title>{{ context.headline }}</h1>
-	<span data-caption>{{ prose(context.prose, context, graphicData) }}</span>
-	<div id="graphic" class="graphic"></div>
-	<ul class="graphic-footer">
-		<li data-note>Note: {{ context.note }}</li>
-		<li data-source>Source: {{ context.source }}</li>
-		<li data-credit>Credit: {{ context.credit }}</li>
-	</ul>
-</div>
-{% endblock content %}
-```
-### Full example with ai2html graphic
-
-For Illustrator graphics, we typically set the title and other info in the Illustrator file itself and not the HTML, so we'd need to add those as nunjucks variables to surface the metadata.
-
-```html
-{% extends 'base.html' %}
-{% set context = data.text %}
-{% set graphicTitle = 'Headline from AI graphic' %}
-{% set graphicAltText = 'Alt text of graphic' %}
-{% set graphicCaption = 'Chatter from AI graphic' %}
-{% set graphicNote = 'Note from AI graphic' %}
-{% set graphicSource = 'Source from AI graphic' %}
-{% set graphicCredit = 'Credit from AI graphic' %}
-{% block  content %}
-<div class="app" data-graphic>
-	<h1 class="graphic-title" data-title>{{ context.headline }}</h1>
-	{{ prose(context.prose, context, graphicData) }}
-	{% set ai2html = "border-map-full" %}
-	{% include "ai2html-output/" + ai2html + ".html" %}
-	<ul class="graphic-footer">
-		<li data-note>Note: {{ context.note }}</li>
-		<li data-source>Source: {{ context.source }}</li>
-		<li data-credit>Credit: {{ context.credit }}</li>
-	</ul>
-</div>
-{% endblock  content %}
-```
-
-### Other metadata
-
-Along with HTML selectors, we also get metadata about graphics through the `project.config.js`. These are global to the whole project and the same for every graphic in the project.
-
-Project config keys output in `manifest.json`
-- `bucket`
-- `createMonth`
-- `createYear`
-- `lastBuildTime`
-- `folder`
-- `id`
-- `tags`
-- `parserOptions`
-  - `metadataIgnore` - This is an array of files or folders that should not be parsed for metadata and displayed in the CMS graphics plugin. For example, any graphics or features created for testing but are not publishable should be added here.
-	- `appleNewsIgnore` - This is an array of files or folders that should be flagged in the CMS as not compatible with Apple News. Use this for graphics that are too dynamic to be accurately captured in a screenshot.
-
-### Sample `manifest.json` output
-
-```json
-[
-  {
-    "title": "Title of graphic",
-    "altText": "Alt text of graphic",
-    "bucket": "graphics.texastribune.org",
-    "graphicPath": "graphics/new-test-2-2021-02/static",
-    "graphicURL": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/",
-    "createMonth": "02",
-    "createYear": "2021",
-    "credits": ["Mandi Cai", "Darla Cameron", "Carla Astudillo", "Chris Essig"],
-    "folder": "graphics/new-test-2-2021-02",
-    "id": "uniqueString",
-    "label": "static/index.html",
-    "lastBuild": "2021-04-22T19:28:30.269Z",
-    "links": [
-      {
-        "url": "https://www.texastribune.org/series/news-apps-graphics-databases/",
-        "text": "See more graphics like this",
-        "isCTA": true
-      }
-    ],
-    "note": "Note: Texas Department of State Health Services was missing data last year.",
-    "previews": {
-      "large": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/preview-large.png",
-      "small": "https://graphics.texastribune.org/graphics/new-test-2-2021-02/static/preview-small.png"
-    },
-    "showInAppleNews": true,
-    "source": "Texas Department of State Health Services and U.S. Census ACS 2018 population estimates"
-  }
-]
-
-```
-
-
-### How it works
-
-The `npm run parse` step will use [Puppeteer](https://github.com/puppeteer/puppeteer) and a local Chrome install to emulate the project in a browser. This will help build metadata based on a graphic's HTML and export image-based previews of the graphic as well as a manifest of all the graphics in the project (`manifest.json`).
-
-#### Troubleshooting
-By default, this process assumes you're using MacOS. To change this for other operating systems, rerun the command with the correct install path variable: `CHROME_INSTALL_PATH="local/path/to/chrome" npm run parse`.