How to add `contentOnly` editing support to a custom block

[bph]

Discussed in https://github.com/WordPress/developer-blog-content/discussions/300

^{Originally posted by **ndiego** September 3, 2024} A lot of work is being done on `contentOnly` editing. While this functionality has been around for a while, upcoming enhancements will make this editing mode commonplace, especially among new users of WordPress. Here are a few related issues/PRs: - https://github.com/WordPress/gutenberg/issues/60021#issuecomment-2325407240 - https://github.com/WordPress/gutenberg/pull/64923 While work is being done to ensure Core blocks work as expect within this editing mode, block developers will need to make modifications to their custom blocks if they want to support this mode. This article will detail what `contentOnly` editing is, how to apply it to blocks, and how to modify custom blocks to support `contentOnly` editing. cc @getdave @noisysocks in case you guys have any thoughts on this article topic.

[getdave]

Thanks for the ping. As you pointed out there is a lot of work around these features at the moment so it's definitely:

• something to better document and surface for authors/developers.
• something to watch for changes in Core (API may evolve...etc).

I have the following from my notes on the topic of Block Editing Mode which may be helpful to you.

---

Block Editing Mode

Controls the editing behavior of individual blocks on a per-block basis, defining whether and how a block can be edited.

State & Package:

The state is state.blockEditingModes, available in the @wordpress/block-editor package (and available in all editors).

Common selector/actions

• getBlockEditingMode()
• setBlockEditingMode()

Note: it is preferred to use the useBlockEditingMode() hook.

Description

Block Editing Mode allows granular control over individual blocks, determining whether a block is fully editable, partially editable, or completely locked. There are three main options:

• Default: - in this mode, all aspects of the block are fully editable. Users can modify content, layout, and any attributes associated with the block. This is the standard editing mode for most blocks.
• Content-only: - Limits the editing to specific attributes marked as "__experimentalRole": "content" in the block’s block.json file. This is designed to simplify the interface and allow users to focus only on content-level changes, hiding more complex options. This mode is typically used in conjunction with template-locked rendering mode to prevent users from modifying layout-related attributes.
• Disabled - The block becomes entirely uneditable and non-selectable in the UI. It remains visible, but users cannot make any changes or interact with it. This is useful for sections of content that should remain static or locked down.

Example

When switching to template-locked rendering mode, the editor automatically applies contentOnly to all blocks within the template, allowing users to edit only content attributes, such as text or images, while preventing changes to layout settings. Blocks within the core/post-content area remain in default mode, allowing full editing of the post content.

[bph]

Also Stabilize role attribute property

[ndiego]

The first draft is complete and ready for review: https://docs.google.com/document/d/12ZrWIH5rxrIdY9rOIs6CfU87EI6H0IBlmP3fm3zCRok/edit?tab=t.0

@getdave given your work on stabilizing the role property, any feedback on the article would be appreciated. 🙏