Batch from data
Render many films from one page, with a --param for each row of your data.
At the end of this page you have one page and a list of films, one for each row of your data. Each film has its own file name.
You need a page that works as one film.
What vawe does and does not do
vawe has no verb or flag that reads a CSV or JSON file. It has one input for a page: the paramA param is a page option that you pass with --param key=value, and the page reads it with new URLSearchParams(location.search).. A param is a key=value pair that you pass on the command line. The page reads it. Your script reads the rows of your data and runs the verb once for each row.
The --param flag exists on four verbs: dev, ship, still and sheet. It is repeatable, with a different key each time. The same key twice stops the verb with the error --param look is given twice: a page reads one value per key. A flag without an equals sign stops it with --param needs key=value.
A param is part of the render keyThe render key is a short hash of the page folder, core/ and the render settings, including each param.. The default output name also carries it, so two rows do not overwrite each other. For --param look=riso on the page films/card/page.html, the draft is out/card-look-riso-draft.mp4.
Steps
Read the param in the page
The page reads location.search. Give each param a default, so the page also renders with no param.
<h1 id="name"></h1>
<script>
const params = new URLSearchParams(location.search);
document.getElementById('name').textContent = params.get('name') ?? 'Hello';
</script>The script runs before the first frame. It reads only the query string, so the page keeps its determinismDeterminism means that the same page gives the same frames on every render, in any order.: the same page and the same param give the same frames. Read Determinism.
Look at one row
bin/vawe still films/card/page.html --at 2 --param name="Ada Lovelace"still writes a PNG of the frame with the param applied. Check one row of each kind before you render all of them: the longest name, the shortest name, and a name with a character your font lacks.
Draft each row
bin/vawe dev films/card/page.html --param name="Ada Lovelace" --silent
bin/vawe dev films/card/page.html --param name="Grace Hopper" --silentWrite the loop in your own script. It reads your CSV or JSON and starts one dev for each row.
Ship each row
bin/vawe ship films/card/page.html --param name="Ada Lovelace"
bin/vawe ship --status --waitship runs in the background. It is refused until a fresh review of the page and the owner’s approval exist. The same flags work with --aspect, so one row and one aspect make one file. Read Ship.
What to keep in mind
- A param is a string. The page converts it. Parse numbers in the page and give them a default.
- The layout must fit the longest value. The checks run on the rows you render. Draft the extremes.
- A param goes to a page only.
still,sheetand the other verbs refuse--paramfor an mp4 input.
Common mistakes
| What you see | Why | What to do |
|---|---|---|
--param needs key=value, got "..." | No equals sign | Write --param key=value |
--param look is given twice | Two values for one key | Render the two values in two calls |
| The page shows its default | The key in the page differs from the flag | Match the key name exactly |
--param goes to a page | The input is an mp4 | Pass the page.html path |
What to read next
CLI
Render flags
Vertical social
Data story
From the blogBatch render videos from one HTML template