Skip to content

Latest commit

 

History

History
147 lines (97 loc) · 5.47 KB

readme.rst

File metadata and controls

147 lines (97 loc) · 5.47 KB
Raw

usda-plant-hardiness

To understand how we set up the maps for this story, check out [our blog post](https://blog.apps.npr.org/2024/11/26/slippy-maps.html) on the subject

This news app is built on our interactive template. Check the readme for that template for more details about the structure and mechanics of the app, as well as how to start your own project.

Getting started

To run this project you will need:

  • Node installed (preferably with NVM or another version manager)
  • The Grunt CLI (install globally with npm i -g grunt-cli)
  • Git

With those installed, you can then set the project up using your terminal:

  1. Pull the code - git clone git@github.com:nprapps/usda-plant-hardiness
  2. Enter the project folder - cd usda-plant-hardiness
  3. Install dependencies from NPM - npm install
  4. Pull the latest content — grunt docs sheets sync
  5. Start the server - grunt

Running tasks

Like all interactive-template projects, this application uses the Grunt task runner to handle various build steps and deployment processes. To see all tasks available, run grunt --help. grunt by itself will run the "default" task, which processes data and starts the development server. However, you can also specify a list of steps as arguments to Grunt, and it will run those in sequence. For example, you can just update the JavaScript and CSS assets in the build folder by using grunt bundle less.

Common tasks that you may want to run include:

  • sheets - updates local data from Google Sheets
  • docs - updates local data from Google Docs
  • sync - syncs files in src/assets/synced/ (usually media files) to S3
  • google-auth - authenticates your account against Google for private files
  • static - rebuilds files but doesn't start the dev server
  • cron - runs builds and deploys on a timer (see tasks/cron.js for details)
  • publish - uploads files to the staging S3 bucket
    • publish:live uploads to production
    • publish:simulated does a dry run of uploaded files and their compressed sizes

You can also chain commands and pass flags for the deploy target: * grunt sync docs sheets static publish - publish to stage * grunt sync:live docs static publish:live - publish to production

Data sources

Jupyter Notebook for processing PRISM minimum temperature data: https://github.com/nprapps/PRISM-min-temp

Custom events

This project fires some custom GA events:

  • location lookup — User looked up a location. Also tracks the location folks looked up.
  • surprise me button clicked - User clicked the "surprise me" button. Also tracks the location folks were sent to
  • explore mode button clicked - User clicked on the "Explore Mode" button. Also tracks which version of the button was clicked (sticky-nav and final).
  • switch location button clicked - User clicked on the "Switch location" button. Also tracks which version of the button was clicked (sticky-nav and final).
  • back to story button clicked - While in "Explore Mode," user clicked on the "Back to Story" button.
  • extension detail button clicked - User clicked to read more of the extension office accounts.
  • click - User clicked anything with a data-tracker attribute (which provides the event label). Used mostly for footer links.

Useful conventions in the content doc

Most slides will be a single image and a single block of text, formatted like:

id: card-id
image: filename.jpg
constrain: contain
align: right

text::
Text goes here
::text

caption::
Optional caption here
::caption

To use the same image for a sequence of text blocks, don't make multiple entries for the image. Instead rework the usual text section as a textBlocks element to loop thorugh.

id: card-id
image: filename.jpg
constrain: contain
align: right
textBlocks:
[.textSections]

text::
First block of text goes here
::text

text::
Next block of text goes here.
::text

text::
Repeat as needed (though consider if you need this many)
::text

[]

Anchoring an image's focal point

When an image is set to contain, it will by default keep the focus on the center of the image as the top or sides are cropped out of view. To shift that focall point, specify an anchor in the doc. For example:

image: 10_19_SPAIN-13.jpg
constrain: contain
anchor: 50% 20%

The first parameter is left/right, the second is top/bottom. (See MDN documentation about object-fit for more.)

Letterboxing images

To letterbox an image on desktop and on mobile, add this param:

constrain: contain

To remove letterboxing, remove that param if it's there.

Show two images side-by-side

type: image
diptych: Nepal-5.jpg, Nepal-6.jpg

Troubleshooting

Fatal error: Port 35729 is already in use by another process.

The live reload port is shared between this and other applications. If you're running another interactive-template project or Dailygraphics Next, they may collide. If that's the case, use --reload-port=XXXXX to set a different port for the live reload server. You can also specify a port for the webserver with --port=XXXX, although the app will automatically find the first available port after 8000 for you.