Locked areas
Lock a block's slot so authors keep its structure, and choose what they may still change.
A block can lock one of its slots. A locked slot holds the blocks it starts with, the
ones its defaultBlock creates when the block is placed, so a designed section keeps
its shape however an author edits the page. The locks use WordPress's templateLock
names and meanings, so authors who know one know the other.
The four locks
import { defineBlock } from "@nextlyhq/plugin-sdk/blocks";
export const hero = defineBlock({
name: "acme/hero",
version: 1,
description: "A headline and a call to action, in that order.",
example: { props: {} },
slots: {
content: {
defaultBlock: [{ type: "acme/headline" }, { type: "acme/button" }],
lock: "all",
},
},
render: ({ renderSlot }) => renderSlot("content"),
});lock | Blocks can be added or removed | Blocks can be moved | What can change |
|---|---|---|---|
"insert" | no | yes | content and design |
"all" | no | no | content and design |
"contentOnly" | no | no | content only |
false | yes | yes | anything (the slot is unlocked) |
A slot that declares no lock takes the lock of the slot its block sits in, so a locked
section stays locked all the way down. false stops that, except beneath
"contentOnly", which nothing inside it can loosen.
Declare what is content
Inside a "contentOnly" slot, only the props a block declares as content can change:
its text, its media, its links. Mark them with role: "content", as a WordPress block
attribute is marked.
import { defineBlock } from "@nextlyhq/plugin-sdk/blocks";
export const headline = defineBlock({
name: "acme/headline",
version: 1,
description: "A heading.",
example: { props: { text: "Title", align: "left" } },
props: {
text: { type: "text", role: "content" },
align: { type: "select" },
},
defaultProps: { text: "Title", align: "left" },
render: ({ props }) => props.text,
});The core blocks already declare theirs: a heading's text and link, an image's media, alt text and caption, a button's label and link, and so on.
Everything else stays as the block started: its other props, its styles, classes, its
root element's id and attributes, visibility, custom CSS and its own lock. So does whether
it renders: a block marked as failing its migration, or at a version ahead of its
definition's, is drawn as a placeholder, and neither can change there. A block that
declares no content props has nothing an author can change inside a "contentOnly" slot.
Its layer name stays editable, since the page never draws it.
Who is held to a lock
Every save, whoever sends it: the editor, the API, an import or an agent. A save that breaks a lock is refused with an error naming the slot and the rule, for example:
The "content" slot of a "acme/hero" is locked "all", so it holds "acme/headline", "acme/button", in that order. It holds "acme/headline".
A lock is measured against the blocks the slot starts with, so changing a locked slot's
defaultBlock changes what every stored page must hold. Bump the block's version and
migrate the pages already stored.
Changing a block's defaultProps doesn't lock existing pages out. Inside a
"contentOnly" slot, a save may keep any value the page already stores in the same
place, or put it back as the block now starts. Only a third value is refused. This
holds for a single as for a collection's page. A localized blocks field keeps what the
same language already stores, never another language's value. A page saved for the
first time, a language saving its first value, and a blocks field inside a field group
are measured against the starting blocks alone. So a stored field-group value whose
"contentOnly" child kept an older value is refused on its next save: put that child
back as the block now starts, and the save goes through.
A page placing a component keeps what the component itself holds.
A block locked in Layers
An author can also lock one block in Layers. That lock is different from a slot's: it is a convenience that anyone who may edit the page can lift, not a rule a block declares, and it covers the block and everything inside it. While a block is locked, nothing may change it or anything inside it, its name included; it can't be moved or deleted, and neither can a block that holds it; and nothing can be moved out of it or added to it. Changing only the lock is always allowed.
Every save is held to it, the API's and an agent's included. A save is compared with
the page as stored, its working draft where there is one: a block locked there may
not change, move or disappear, and the save is refused with the code
layers-lock-changed, naming the block. A save that empties the whole field, by
setting it to null, is refused the same way while the page holds a locked block, on
the data the save's hooks leave: a hook that empties the field is refused as the
caller would be. A block added before a locked one, or a block removed from before it,
shifts its position without moving it, so that is allowed. A reorder is read as the
fewest blocks moved that explain it: moving another block across the locked one is that block's move and is
allowed, while moving the locked block past more of its neighbours than would have to move
round it is a move of the locked block, and refused. The same holds for a block that
holds it. The editor asks the same question of a move before it is made. To change or
move a locked block, send it unlocked in the same save.
A known limit: a script or API write can swap a locked block with the block next to it, since that looks the same as the neighbour moving; the editor refuses it.
Deleting is the exception. A locked block can't be deleted in the same save that unlocks it, and neither can a block that holds it: unlock it and save first, then delete it in a second save. The editor says so: until the unlock is saved, Delete is greyed with "Save first: this block is still locked on the saved page."
In the editor, a locked block shows a lock in Layers and "Locked" on its toolbar. Every block inside it shows "Locked by" the block's name, and its controls are read-only. Moving, deleting or changing any of them is refused before it happens, with the reason: in Layers, on the canvas, on the toolbar, from the keyboard and in the inspector. A click still selects a locked block, so you can unlock it from the block's menu.
Some saves can't be checked, and are kept with a line in the server log saying so:
- a blocks field inside a group or a repeater, whose stored value can't be read;
- a localized blocks field whose language can't be read yet.
Components and locks
A lock inside a component holds on every page that places it. A placement cannot use an exposed field or an exposed slot to change what the lock holds, and such a page is refused, naming the placement.
A block locked in Layers inside a component holds on every page that places it too. A
placement's value for an exposed field, or its content for an exposed slot, cannot
change it, even on a placement a visibility condition hides, and the save is refused
with layers-lock-changed, naming the block. A page cannot unlock it: remove the value, or
unlock the block in the component. A value a page already stores is kept, so locking a
block after pages gave it values refuses only a new one. A component's variant is held
the same way: a variant that sets a value on a block the component locks is refused when
the component is created or saved, naming the block and the variant, including a lock
the same save adds and a block locked inside a component it places. A page that chooses a
variant hiding or changing such a block is refused as a value would be.
In the editor, the field that drives such a block is read-only on the placement, with "Set
by the component" and its name, and where to change it. Double-clicking its text on the
canvas says the same rather than opening it for editing. A field held by a
"contentOnly" area is read-only the same way, with that area's reason.
A component cannot add an exposed field that drives something a "contentOnly" lock
holds, since no placement could change it. Expose a content field instead, remove the
exposure, or loosen the lock on that slot. An exposure a component already stores is
kept, and reported in the server log, so an unrelated edit still saves.
Registration refuses a lock value other than the four, and a role other than
"content", naming the block. nextly generate refuses them too, so a block manifest
is never written for blocks the app would refuse at boot.