Components
A component is a group of blocks saved to a file. Its layout is shared by every page that uses it. Each page keeps its own words, unless you lock a field.
Some arrangements of blocks come back again and again: a pricing table, a team grid, a call to action at the foot of every service page. A component saves one arrangement, with everything inside it, to a file. Every page that uses it shares its structure, and each page writes its own words.
Saving a component
Hover a block on the page, open the More menu on its handle and choose Save as a component…. Give it a name, like “Pricing”. The block and every block inside it become components/pricing.json, and the block on the page becomes the first use of the component, still showing what it showed before.
From then on, the component appears in the Blocks library beside the blocks, rendered with its starting content. Drag it into any block area that takes its outer block. A component can't be dropped inside another component.
What is shared
| Part | Shared or per page |
|---|---|
| Which blocks, in what order and nesting | Shared by every page |
| The blocks' own templates and classes | Shared, as with any block |
| Text and rich text | Per page, unless locked |
| Images | Always per page |
A new use starts with the text the component was saved with, so an editor sees a filled-in example to write over. Images aren't carried across, because each page keeps its images in its own folder.
Locking fields
Some text should read the same everywhere, like a plan's price or a legal line. Choose Lock fields… from the component's menu and tick the fields to share. A locked field reads the same on every page that uses the component, and editing it on any page changes all of them. The editor marks locked fields on the page with a small lock, and a message says how many pages a change reaches.
Unlocking a field lets each page write its own copy again. The page you unlock it on keeps the shared text, and new uses start with it. Images can't be locked, because each page keeps its own.
Changing the structure
On a page, a component moves as one piece: its handle moves, copies or removes the whole thing. To change what's inside it, choose Edit structure for all pages. The blocks inside get handles of their own, marked “all pages”, and moving, duplicating or removing them changes the component file, so every page that uses it follows. Choose Done editing structure to go back.
The outer block can't be removed this way. To take the component off one page, remove it from that page.
Detaching
Detach from component turns one use back into ordinary blocks with the same content. That page no longer follows the component, and the others are untouched. It's the way to make a one-off variation.
The files
A component is plain JSON, readable and editable by hand:
{
"name": "pricing",
"label": "Pricing",
"tree": [
{ "block": "card-grid", "key": "k1", "blocks": {
"items": [
{ "block": "plan", "key": "k2" },
{ "block": "plan", "key": "k3" }
]
} }
],
"shared": { "k2.price": "$12", "k3.price": "$29" },
"defaults": { "k1.heading": "Simple pricing", "k2.name": "Solo", "k3.name": "Studio" }
}
tree is the structure. Each block in it has a key, and content is named by key and field: k2.price. shared holds the locked fields. defaults holds what a new use starts with. On the page, a use is small:
"sections": [
{ "id": "b-5e21aa", "component": "pricing", "fields": { "k1.heading": "Plans for teams" } }
]
When the site is built, each use is expanded into ordinary blocks and checked like them. A use whose component file is missing, or a component whose outer block isn't allowed in the block area it's in, stops the build with the page named.