Blocks: Deprecate non-string descriptions #44455
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tyxla
added
[Type] Enhancement
tyxla
requested review from
fullofcaffeine,
simison,
mtias,
gziolo,
noahtallen,
ntsekouras and
Addison-Stavlo
|
Size Change: +264 B (0%) Total Size: 1.26 MB
ℹ️ View Unchanged
|
gziolo
approved these changes
Sep 26, 2022
There was a problem hiding this comment.
We encourage using block.json files when registering blocks, so this is automatically enforced when devs follow this approach.
I like the idea of soft deprecation as it was only documented as string 👍🏻
At some point, we can simply ignore non-string values passed as description but still register blocks for backward compatibility.
We will need a dev note and a note in the CHANGELOG file for the @wordpress/blocks package.
In #41236 we list the following item:
Consider adding SlotFill for the block's description in the sidebar to allow custom code. At the moment we use block's description which is a simple string. However, it would be sometimes useful to include some custom HTML code like .
That could be an alternative approach for block authors that want to provide more complex description for the block.
gziolo
added
[Feature] Block API
WordPress 6.2 Dev noteIn WordPress 6.2, non-strings as block descriptions have been deprecated. Previously, we could register a block with a non-string description (like a React Node or any other JavaScript object for example). Another way to achieve that was to use the While there could be niche edge cases that found non-string descriptions useful, we discovered that this could cause unexpected bugs and thus have made the decision to deprecate it. This makes it clearer that the recommended type for block descriptions should be of type |
tyxla
added
has dev note
|
Thanks for taking a look, both 🙌
Added a dev note above, and a CHANGELOG entry. |
ndiego
added
the
Backport to WP Beta/RC
|
@tyxla was this change meant for 6.1 or are we aiming for 6.2? |
ndiego
removed
the
Backport to WP Beta/RC
|
I meant to get this into 6.2. No rush for 6.1 😉 Thanks for double-checking. |
|
@tyxla After this change, what is the best way to pass a link into the description? We've been using |
|
@kraftbj making the description non-string might cause unexpected breakage here and there, as the editor expects block descriptions always to be strings, and doesn't really support React nodes or any other objects. So the answer here is really that we shouldn't be passing a link to the description. I know that's not ideal, but at the same time descriptions could be used in other areas that are treated as strings, and then an object or React node just doesn't work. One way forward, of course, is to continue relying upon the deprecated functionality, but there's no guarantee it will not be dropped in a future release. IMHO ideally, coming up with another place to put that link would be perfect. Perhaps we could create another section that is displayed right under the block description in the sidebar, and we can render what we want there? Alternatively, a new filter could be introduced that would be responsible only for the rendered block description in one or more areas, and then that filter could be used in Jetpack to provide alternative content to render. Another alternative could be implementing a first-party Let me know if that helps. |
This is exactly what @mtias suggested a few months back. It's being tracked as a bullet point in #41236:
@tyxla or @kraftbj, feel free to open an issue with more details based on what you need in Jetpack. |
I created an issue here: #49887 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
This PR deprecates non-string descriptions for blocks.
Why?
Non-strings (for example, React nodes) have been implicitly allowed forever. However, using non-strings for block description can cause subtle bugs, and it would be ideal if we explicitly deprecate it. We're still maintaining support for it, though, in order to avoid breaking anything that relies on that behavior.
See #44233 and discussion there for context.
How?
We're simply adding a
deprecated()for the case where a block is registered with, or later filtered to, a non-string description. We're also adding a few tests to cover this behavior, and ensure that we still support non-strings, but warn developers for undesired usage.Testing Instructions