[Documentation] Adding @example entries to the public API exposed in core/blocks
#42745
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
ryanwelcher
changed the title
@example entries to the public API exposed in core/blocks
19 tasks
ryanwelcher
added
[Type] Developer Documentation
|
Size Change: +5.75 kB (0%) Total Size: 1.27 MB
ℹ️ View Unchanged
|
talldan
reviewed
Jul 28, 2022
| * registerBlockType( 'namespace/block-name', { | ||
| * title: __( 'My First Block' ), | ||
| * edit: () => <div>{ __( 'Hello from the editor!' ) }</div>, | ||
| * save: () => <div>{ __( 'Hello from the saved content!' ) }</div>, |
There was a problem hiding this comment.
This example could be misleading, as typically save output can't be internationalised.
As the saved content is static within a post it wouldn't have the desired effect, and it may cause block validation issues if the block is saved in one language and loaded in another.
It might be good to remove the __. Maybe just have a minimal example of using an attribute?
edit: ( { attributes } ) => <div>{ attributes.content }</div>,
save: ( { attributes } ) => <div>{ attributes.content }</div>,There was a problem hiding this comment.
This is very interesting. Has this been tested? If this is the case, we'll need to change other reference such as the create-block template as well. cc @gziolo
There was a problem hiding this comment.
The rule to follow for static blocks is that the save function return value needs to be determined entirely from attributes or hard-coded values, it can't use outside data of any kind.
Checking the codebase this bug seems to already exist in the file block (it's the only one that uses __ in a save function.)
To repro:
- Upload a pdf to a file block
- Publish the post
- Change to a different language
- Reload the post in the editor
- Observe that the file block now has a validation error
I would recommend reproducing without the Gutenberg plugin active, as a lot of the translations are missing (at least for the dev version).
I'll make a seperate bug report for it if there isn't one already. (#43013)
There was a problem hiding this comment.
Great catch @talldan with the File block and the translation used with the aria-label attribute 👍🏻 This is also a great example of where we could benefit from dynamic tokens that can be replaced on the server as discussed in #39831.
If this is the case, we'll need to change other reference such as the create-block template as well.
Yes, that is a great point. It never occurred to me that it might cause issues but now it seems so obvious 🙈
There was a problem hiding this comment.
OK cool. I'll update the example here and then do a PR to change the template the create-block package and related items.
…@ignore getBlockVariations.
gziolo
approved these changes
Aug 8, 2022
packages/blocks/README.md
Outdated
| registerBlockType( 'my-collection/block-name', { | ||
| title: __( 'My First Block' ), | ||
| edit: () => <div>{ __( 'Hello from the editor!' ) }</div>, | ||
| save: () => <div>{ __( 'Hello from the saved content!' ) }</div>, |
There was a problem hiding this comment.
As pointed out by @talldan, let's avoid using translations with save.
There was a problem hiding this comment.
That's odd, I thought I removed it. Thanks for catching this!
| onClick={ () => { | ||
| registerBlockStyle( 'core/quote', { | ||
| name: 'fancy-quote', | ||
| label: __( 'Fancy Quote' ), |
There was a problem hiding this comment.
One thing that should be included as a note is how CSS styles can be wired with a newly registered variation. Maybe it's enough to link to the documentation that explains all the details:
| @@ -720,6 +756,30 @@ _Returns_ | |||
|
|
|||
| Registers a new block variation for the given block type. | |||
There was a problem hiding this comment.
We can reference here the documentation page:
| * import { registerBlockCollection, registerBlockType } from '@wordpress/blocks'; | ||
| * | ||
| * // Register the collection. | ||
| * registerBlockCollection( 'my-collection', { |
There was a problem hiding this comment.
Do we have any detailed documentation for block collections? It would be great to have on presenting how to group blocks in the inserter by shared namespace.
There was a problem hiding this comment.
I don't believe we do. I have it on my list to create some.
Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
…ordPress/gutenberg into feature/add-examples-public-blocks-api
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?
Based on the discussion in #42637 (review), this PR adds examples for the public API that is exposed for the
core/blockspackage. Part of the effort in #42125Why?
The actions that were documented originally here, have been marked as
@ignoreto discourage their use in favor of the public API available here. We still need examples for these functions.