search

the-pudding / music-map-story

MIT License
0 stars 0 forks source link

readme

or just add the circle layer programmatically as a static and style everything using the front end. https://docs.mapbox.com/help/tutorials/static-images-style-params/?size=n_10_n https://github.com/mapbox/mapbox-sdk-js/blob/main/docs/services.md#getstaticimage

generate hex grids instead of boundaries...problem with boundaries is need to load on front end https://gist.github.com/clhenrick/5787a12a8bf3b02821839e4f9556d997

Development

Run npm start to fire up the project server. control + c to stop.

Any changes to the src/ folder will trigger live reload.

HTML

Where it goes: src/html/partials/story/.

The main HTML file is src/html/index.hbs. Generally speaking, You should mostly just include new partials in there and not modify too much of it since there are a bunch of presets.

Partials are not automatically included. You must add them to index.hbs. If you created a new file content.hbs it would be referenced as {{> story/content }}.

Sticky Header

Change base/header in index.hbs:

To use the menu but without it being sticky, simply changed position fixed to position absolute in header.styl.

To add in the patreon message and list, uncomment {{> base/patrons }} in sticky.hbs. Running npm run doc will update to latest patrons.

Metadata

Fill out data/meta.json

Copy

Using a Google Doc for copy is recommended. We use ArchieML as a micro CMS.

Setup Google doc

Running npm run doc at any point (even in new tab while server is running) will pull down the latest, and output a file data/doc.json.

You can now reference the JSON in your HTML, namespaced by doc (eg. <p>{{doc.explanation}}</p>).

You can also do the same with a Google Sheet.

SVG Icons

There is a directory called svg in the root of project, it contains a bunch of icons. To include them in the HTML, simply do this:

<img inline src='arrow-left.svg'>

This way you can drop in svg icons anywhere in your HTML code whilst keeping it uncluttered.

JavaScript

Where it goes: src/js/

Take a look at main.js. This is the kickoff file, the only one included and run automatically.

Then take a look at graphic.js, it has some basic skeleton stuff setup for you. This is imported and called from main.js once on load, and subsequently on a debounced resize event. I recommend putting your code in here. If you want to create more files, I recommending doing that in graphic.js, but remember they won't be executed until you import them.

D3 is included globally by default. For any other libraries, it is recommend that you use npm to install and import them. You can also do it the vanilla way by including them in the src/assets folder and putting a script tag in the HTML.

The JavaScript is transpiled from ES6, and uses Parcel to bundle into a single file. That means each file creates its own closure, so a "global" variable is scoped to a file unless you declare it as window.variable = .....

Installing Libraries

NPM way: npm install [name] --save. Usage: (see library docs, but usually) import [library] from '[library]'

Old school: Put JS file in the src/assets/scripts directory. Usage: reference in the index.hbs file <script src='assets/scripts/[name].js'></script>

Helper Functions

In the folder src/js/utils there a are a bunch of handy helper JS functions.

To use these, at the top of your .js file, include import functionName from './utils/useful-thing.js'

If there is only one exported function, you can use it in your file with just functionName(). Otherwise, you'll need functionName.specificFunction().

Slider

NoUISlider is included by default, with some preset pudding styles. To include it, simply include the library in your JS file import noUiSlider from 'nouislider'. Then in src/css/config.styl, uncomment no-ui-slider.styl.

Google Sheet

You can pull down a Google Sheet to JSON to include in your JS, or use for templating HTML. Make the sheet sharable, then fill out config.json with the details. By default it will be the file in data/sheet.json which you could use for HTML. You can have it save anywhere by supplying a custom filepath (eg. src/js/example.json or src/assets/data/example.json).

CSS

Where it goes: src/css/story/.

There is a file for you to start off with, story.styl. You can create as many files as you want in this directory, they are automatically included. Note: You must restart the server when you create a new stylus file.

Checkout some of the auto-included files in src/css/utils/ (variables.styl, helpers.styl, presets.styl). You can modify these, especially variables.styl.

Fonts

Fonts are loaded async and use the font-display swap CSS setting.

Available font-weights (bold means it is loaded by default):

Variable names in stylus (use these for font-family since they contain proper fallbacks):

Assets

Put everything (images, audio, data, etc) in src/assets/.

When deployed, assets paths will remain relative. However, you'll notice that in index.hbs there is a line like <script src='{{basepath}}assets/scripts/d3.v5.9.1.min.js'></script>. basepath here switches from nothing in local development, to https://pudding.cool/ in production. We have a common assets folder for stuff like (which also occurs with fonts). If you need to use this project for a non-Pudding one, make sure to update the data.basepath variable in scripts/html.js.

Deploy

Run npm run deploy

This generates a single html file with inlined css, a single js file, and a folder with assets in the dist folder. It also will automatically optimize jpg and png files in the folders assets/social and assets/images.

Github Pages

Run make github (make sure you've enabled github pages in your repo settings to pull from docs).

Password Protection

In the package.json file, modify the password in the protect script. If using Netlify, make npm run protect the build script.

S3

Requirements:

In Makefile, replace year/month/name with your own (eg. 2017/01/nba). Uncomment code.

Run make pudding to deploy and bust cache. If you only made changes to html/css/js, you can run make aws-htmljs then make aws-cache (it will be much quicker than re-uploading all your assets).

Launch Checklist

Future Proofing

Here are some best practices to follow to increase the likelihood that the story doesn't break in the near future.