You're reading docs for Nextly Alpha. APIs may change between releases.

Page Builder

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"),
});
lockBlocks can be added or removedBlocks can be movedWhat can change
"insert"noyescontent and design
"all"nonocontent and design
"contentOnly"nonocontent only
falseyesyesanything (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.