How to add contentOnly editing support to a custom block

[bph]

Discussed in #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:

• Writing and contentOnly modes gutenberg#60021 (comment)
• Experiment with block drill down in contentOnly mode gutenberg#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. 🙏

[getdave]

@ndiego I'll add to my todo. Just getting back to AFK and focusing on 6.7 now but will get around to this. What's your timeline here?

[ndiego]

@ndiego I'll add to my todo. Just getting back to AFK and focusing on 6.7 now but will get around to this. What's your timeline here?

I'd love to get this posted early this week if possible. I'm mainly just looking for a technical review to make sure there is nothing glaringly wrong or important info I am missing. If there is anyone else you recommend pinging, just let me know. 🙏

[ndiego]

The first review is complete. Any further edits should still be added to the Google Doc, but I have proactively drafted the article (public preview).

[getdave]

@ndiego I took a look and didn't notice anything obvious. Great job 👍

[ndiego]

Thanks @getdave! Moving on to publication.

[ndiego]

Post has been published: https://developer.wordpress.org/news/2024/11/05/how-to-add-content-only-editing-support-to-a-block/

Social Post copy:

In WordPress 6.7, content-only editing has been stabilized for use in custom blocks. Discover what this mode is, why your blocks should support content-only editing, and how to implement it effectively.

[justintadlock]

This is currently scheduled for November 12th on socials.

[ndiego]

This is currently scheduled for November 12th on socials.

@justintadlock, that's the date of the WordPress 6.7 release. Maybe we can move it to later in the week? I imagine there will be a lot of 6.7 posts on Tuesday.

[justintadlock]

Ah, I forgot. It should get rescheduled.

[justintadlock]

It's rescheduled for Thursday instead.