Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Documentation] Adding @example entries to the public API exposed in core/blocks #42745

Merged
merged 13 commits into from
Aug 8, 2022
Merged

[Documentation] Adding @example entries to the public API exposed in core/blocks #42745

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
0cf85d1
Adding a simple example and reference to the Create a block tutorial.
ryanwelcher Jul 27, 2022
e8dd7c7
Add examples for registerBlockCollection and unregisterBlockType.
ryanwelcher Jul 27, 2022
a3e28bc
Add examples for setDefaultBlockName and setGroupingBlockName.
ryanwelcher Jul 27, 2022
e302a88
Add example for setCategory.
ryanwelcher Aug 4, 2022
2e32e3d
Add example for updateCategory and @ignore getCategories in favor of …
ryanwelcher Aug 4, 2022
f9f6859
Add examples for registerBlockStyle and unregisterBlockStyle.
ryanwelcher Aug 4, 2022
7fc7b90
Add examples for registerBlockVariation, unregisterBlockVariation, an…
ryanwelcher Aug 4, 2022
bca3a77
Add example for unregisterBlockCollection.
ryanwelcher Aug 4, 2022
fb82046
Update registerBlockType example to remove i18n in save property.
ryanwelcher Aug 5, 2022
40dfff9
Update packages/blocks/README.md
ryanwelcher Aug 8, 2022
e3a36f3
Updates per code review.
ryanwelcher Aug 8, 2022
07f6196
Merge branch 'feature/add-examples-public-blocks-api' of github.com:W…
ryanwelcher Aug 8, 2022
c39c0b7
Rebuild docs to include the committed suggestion.
ryanwelcher Aug 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions packages/blocks/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -685,6 +685,25 @@ _Returns_

Registers a new block collection to group blocks in the same namespace in the inserter.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { registerBlockCollection, registerBlockType } from '@wordpress/blocks';

// Register the collection.
registerBlockCollection( 'my-collection', {
title: __( 'Custom Collection' ),
} );

// Register a block in the same namespace to add it to the collection.
registerBlockType( 'my-collection/block-name', {
title: __( 'My First Block' ),
edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
save: () => <div>{ __( 'Hello from the saved content!' ) }</div>,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As pointed out by @talldan, let's avoid using translations with save.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's odd, I thought I removed it. Thanks for catching this!

} );
```

_Parameters_

- _namespace_ `string`: The namespace to group blocks by in the inserter; corresponds to the block namespace.
Expand All @@ -707,6 +726,21 @@ Registers a new block provided a unique name and an object defining its
behavior. Once registered, the block is made available as an option to any
editor interface where blocks are implemented.

For more in-depth information on registering a custom block see the [Create a block tutorial](docs/how-to-guides/block-tutorial/README.md)

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'namespace/block-name', {
title: __( 'My First Block' ),
edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
save: () => <div>{ __( 'Hello from the saved content!' ) }</div>,
} );
```

_Parameters_

- _blockNameOrMetadata_ `string|Object`: Block type name or its metadata.
Expand Down Expand Up @@ -774,6 +808,20 @@ _Parameters_

Assigns the default block name.

_Usage_

```js
import { setDefaultBlockName } from '@wordpress/blocks';

const ExampleComponent = () => {
return (
<Button onClick={ () => setDefaultBlockName( 'core/heading' ) }>
{ __( 'Set the default block to Heading' ) }
</Button>
);
};
```

_Parameters_

- _name_ `string`: Block name.
Expand All @@ -790,6 +838,20 @@ _Parameters_

Assigns name of block for handling block grouping interactions.

_Usage_

```js
import { setGroupingBlockName } from '@wordpress/blocks';

const ExampleComponent = () => {
return (
<Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
{ __( 'Set the default block to Heading' ) }
ryanwelcher marked this conversation as resolved.
Show resolved Hide resolved
</Button>
);
};
```

_Parameters_

- _name_ `string`: Block name.
Expand Down Expand Up @@ -858,6 +920,23 @@ _Parameters_

Unregisters a block.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { unregisterBlockType } from '@wordpress/blocks';

const ExampleComponent = () => {
return (
<Button
onClick={ () => unregisterBlockType( 'my-collection/block-name' ) }
>
{ __( 'Unregister my custom block.' ) }
</Button>
);
};
```

_Parameters_

- _name_ `string`: Block name.
Expand Down
78 changes: 78 additions & 0 deletions packages/blocks/src/api/registration.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,9 +231,23 @@ function getBlockSettingsFromMetadata( { textdomain, ...metadata } ) {
* behavior. Once registered, the block is made available as an option to any
* editor interface where blocks are implemented.
*
* For more in-depth information on registering a custom block see the [Create a block tutorial](docs/how-to-guides/block-tutorial/README.md)
*
* @param {string|Object} blockNameOrMetadata Block type name or its metadata.
* @param {Object} settings Block settings.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockType } from '@wordpress/blocks'
*
* registerBlockType( 'namespace/block-name', {
* title: __( 'My First Block' ),
* edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
* save: () => <div>{ __( 'Hello from the saved content!' ) }</div>,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@talldan talldan Aug 5, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Upload a pdf to a file block
  2. Publish the post
  3. Change to a different language
  4. Reload the post in the editor
  5. 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)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🙈

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK cool. I'll update the example here and then do a PR to change the template the create-block package and related items.

* } );
* ```
*
* @return {?WPBlockType} The block, if it has been successfully registered;
* otherwise `undefined`.
*/
Expand Down Expand Up @@ -343,6 +357,24 @@ function translateBlockSettingUsingI18nSchema(
* @param {Object} settings The block collection settings.
* @param {string} settings.title The title to display in the block inserter.
* @param {Object} [settings.icon] The icon to display in the block inserter.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { registerBlockCollection, registerBlockType } from '@wordpress/blocks';
*
* // Register the collection.
* registerBlockCollection( 'my-collection', {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe we do. I have it on my list to create some.

* title: __( 'Custom Collection' ),
* } );
*
* // Register a block in the same namespace to add it to the collection.
* registerBlockType( 'my-collection/block-name', {
* title: __( 'My First Block' ),
* edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
* save: () => <div>{ __( 'Hello from the saved content!' ) }</div>,
* } );
* ```
*/
export function registerBlockCollection( namespace, { title, icon } ) {
dispatch( blocksStore ).addBlockCollection( namespace, title, icon );
Expand All @@ -363,6 +395,24 @@ export function unregisterBlockCollection( namespace ) {
*
* @param {string} name Block name.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { unregisterBlockType } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () =>
* unregisterBlockType( 'my-collection/block-name' )
* }
* >
* { __( 'Unregister my custom block.' ) }
* </Button>
* );
* };
* ```
*
* @return {?WPBlockType} The previous block value, if it has been successfully
* unregistered; otherwise `undefined`.
*/
Expand Down Expand Up @@ -427,6 +477,20 @@ export function getUnregisteredTypeHandlerName() {
* Assigns the default block name.
*
* @param {string} name Block name.
*
* @example
* ```js
* import { setDefaultBlockName } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
*
* return (
* <Button onClick={ () => setDefaultBlockName( 'core/heading' ) }>
* { __( 'Set the default block to Heading' ) }
* </Button>
* );
* };
* ```
*/
export function setDefaultBlockName( name ) {
dispatch( blocksStore ).setDefaultBlockName( name );
Expand All @@ -436,6 +500,20 @@ export function setDefaultBlockName( name ) {
* Assigns name of block for handling block grouping interactions.
*
* @param {string} name Block name.
*
* @example
* ```js
* import { setGroupingBlockName } from '@wordpress/blocks';
*
* const ExampleComponent = () => {
*
* return (
* <Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
* { __( 'Set the default block to Heading' ) }
* </Button>
* );
* };
* ```
*/
export function setGroupingBlockName( name ) {
dispatch( blocksStore ).setGroupingBlockName( name );
Expand Down