Skip to content

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)

  • manageExtensionConfig with draft: true makes add, remove, update, exclude and restore change 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 publishDraft puts the draft live. When the live blocks changed after the draft was started it answers status: conflict (with liveChangedAt) and changes nothing; send force: true to publish anyway. discardDraft drops the draft.
  • extensionConfig tells whether a page has a draft (draft: "unpublished"), and with draft: true lists the draft's blocks (draft: "showing").
  • manageExtensionConfig previewDraft answers 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.