Block Drafts¶
An owner can change a page's content blocks, preview the result on the real shop, and publish it when it's ready. Until then shoppers see the page as it was. Drafts cover content blocks only; a page's own fields (name, description, layout) still save straight away.
Pages only so far. Collections, page types (stereotypes) and products still save their blocks live.
For shop owners¶
On a page's Content blocks tab (Site → Pages → edit), a bar above the blocks says whether you are changing the live page or a draft.
- Start a draft starts a draft from the page's current blocks. From then on everything you do on the tab (adding, changing, hiding, removing or restoring blocks) is saved to the draft, not the live page.
- Preview draft opens your shop's preview on this page, in a new tab, with the draft's blocks. It is the same private preview as theme and style previews (Theme and Style Preview): one preview per shop, behind a link only you hold, with a yellow bar under the header. While you are in it, every page that has a draft shows its draft. The bar says when the page you're looking at is a draft, and offers Publish or discard this page's draft, which brings you back to the page's Content blocks tab.
- Publish puts the draft's blocks live and ends the draft.
- Discard throws the draft away; the live page is unchanged.
If someone changes the live page's content blocks after you started the draft (for example by editing them directly, or through an AI assistant), Publish doesn't overwrite their change. It warns you, with when the live page was last saved, and offers Publish anyway (your draft replaces their change) or Discard draft. Changing the page's own fields, such as its name, is not a conflict.
Settings → Preview lists every page that has a draft, with a link to each, and opens the preview even when no design change is waiting.
From an AI assistant (MCP)¶
manageExtensionConfigwithdraft: truemakesadd,remove,update,excludeandrestorechange the page's draft instead of the live page. The first such call starts the draft from the live blocks. Collections, stereotypes, products and locations answer that only pages have drafts.manageExtensionConfig publishDraftputs the draft live. When the live blocks changed after the draft was started it answersstatus: conflict(withliveChangedAt) and changes nothing; sendforce: trueto publish anyway.discardDraftdrops the draft.extensionConfigtells whether a page has a draft (draft: "unpublished"), and withdraft: truelists the draft's blocks (draft: "showing").manageExtensionConfig previewDraftanswers the shop preview's private link, opening the page with its draft, for the assistant to give you (it opens the preview when none is open).
How it works¶
The draft. One contentDrafts document per item being edited (ContentDraft, commerce-core
extensions.drafts): catalogueId, itemType (PAGE), itemId (the page's id), the whole
block list as the draft has it (extensionConfigurations, exclusions included), basedOnVersion,
basedOnModified, who changed it and when. A unique index on (catalogueId, itemType, itemId)
makes it one draft per item. Drafts live apart from Page, Product, Collection and
stereotypes, so nothing that reads those pays for drafts, and a draft never reaches feeds, search
or a site export. Discarding is deleting the document.
The service. ContentDraftService owns drafts; only ContentDraftServiceImpl touches the
repository. Its block operations (addBlock, updateBlock, moveBlock, removeBlock,
excludeInherited, restoreInherited, saveBlocks) start a draft from the live blocks when there
is none, so a caller never has to; they're there for the visual section editor. Each kind of item is
reached through a ContentDraftTarget (PageDraftTarget uses PageService), so adding drafts for
collections or stereotypes is adding a target.
Editing a draft with the existing editors. The block panel and MCP edit a whole item and save it.
For a page with a draft they're given ContentDraftService.editingCopy: a copy of the page carrying
the draft's blocks (deeply copied, so a cached page is never changed), marked
Page.contentDraft (@Transient, @JsonIgnore; ExtensionConfigurationContainer.isContentDraft()).
ExtensionUtils.saveConfiguration (the block panel) and ExtensionContainerResolver.saveContainer
(MCP, inline editing) send a marked copy to ContentDraftService.saveCopy, never to the page.
ContentDraftSaveGuard refuses to store a marked copy as a page, as a safety net.
Rendering. In a shop preview (SiteContext.isSitePreview(), see Theme and Style
Preview) ExtensionService.renderExtensions and renderOnly render
ContentDraftService.withDraft(item): a copy with the draft's blocks when there is one, the item
itself otherwise. That is one indexed lookup, made only while previewing; shoppers, the admin's
edit mode and inline editing never look. The preview already bypasses the extension model cache and
RenderedFragmentCache, and is private, no-store. When a draft was rendered, the
badger.contentDraftShown request attribute tells SitePreviewInterceptor, whose banner then says
so and links to the page's editor. A preview with no design changes (SitePreview.isEmpty(),
opened by SitePreviewService.open) only shows drafts, and its banner offers no design Publish or
Discard.
Publishing and conflicts. ContentDraftService.publish loads the page through PageService,
compares a fingerprint of its live blocks with basedOnVersion (the fingerprint taken when the draft
started), and only then copies the draft's blocks onto the page, saves it through PageService and
deletes the draft. The fingerprint (ContentDraftBlocks.fingerprint, SHA-256 of the blocks with
map keys sorted) covers blocks only, so editing the page's name or description doesn't make a
draft stale; a page's lastModifiedDate would. With force the check is skipped. Saving the page
fires ExtensionModelCacheInvalidator, which evicts the catalogue's block models on every pod
through SiteCacheService, exactly as any block save does.
Admin. PageAdminRenderer hands the block panel the editing copy when the page has a draft and
puts blockDraft on the model; the bar is admin/extensionEditPanels/blockDraftBar.html.
PageDraftAdminController (/admin/site/pages/drafts/{pageId}/start|preview|publish|discard)
starts, previews (SitePreviewService.open, then the preview link with ?to= the page's path),
publishes and discards. SitePreviewAdminController lists the drafts on Settings → Preview.
Site data. Drafts are never exported or imported (SiteTransferExcludesContentDraftsTest).
SiteDataDeletionService deletes a site's drafts with its catalogue, and deleting a page
(PageService.delete, which publishes a PageIndexEvent DELETE) deletes its draft
(ContentDraftItemDeletionListener).
Not done yet. Drafts for collections, stereotypes and products; drafts in the blog editors (blog posts are pages, but their editor still saves live); several people editing one draft (last write wins); undo beyond discarding.