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 9 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
238 changes: 217 additions & 21 deletions packages/blocks/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,27 +370,6 @@ _Returns_

- `Array`: Block settings.

### getBlockVariations

Returns an array with the variations of a given block type.

_Parameters_

- _blockName_ `string`: Name of block (example: “core/columns”).
- _scope_ `[WPBlockVariationScope]`: Block variation scope name.

_Returns_

- `(WPBlockVariation[]|void)`: Block variations.

### getCategories

Returns all the block categories.

_Returns_

- `WPBlockCategory[]`: Block categories.

### getChildBlockNames

Returns an array with the child blocks of a given block.
Expand Down Expand Up @@ -685,6 +664,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 @@ -696,6 +694,29 @@ _Parameters_

Registers a new block style variation for the given block.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { registerBlockStyle } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
return (
<Button
onClick={ () => {
registerBlockStyle( 'core/quote', {
name: 'fancy-quote',
label: __( 'Fancy Quote' ),
Copy link
Member

Choose a reason for hiding this comment

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

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:

https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-styles.md#styles

} );
} }
>
{ __( 'Add a new block style for core/quote' ) }
</Button>
);
};
```

_Parameters_

- _blockName_ `string`: Name of block (example: “core/latest-posts”).
Expand All @@ -707,6 +728,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 All @@ -720,6 +756,30 @@ _Returns_

Registers a new block variation for the given block type.
Copy link
Member

Choose a reason for hiding this comment

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

We can reference here the documentation page:

https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-variations.md


_Usage_

```js
import { __ } from '@wordpress/i18n';
import { registerBlockVariation } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
return (
<Button
onClick={ () => {
registerBlockVariation( 'core/embed', {
name: 'custom',
title: __( 'My Custom Embed' ),
attributes: { providerNameSlug: 'custom' },
} );
} }
>
__( 'Add a custom variation for core/embed' ) }
</Button>
);
};
```

_Parameters_

- _blockName_ `string`: Name of the block (example: “core/columns”).
Expand Down Expand Up @@ -766,6 +826,37 @@ _Returns_

Sets the block categories.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { store as blocksStore, setCategories } from '@wordpress/blocks';
import { useSelect } from '@wordpress/data';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
// Retrieve the list of current categories.
const blockCategories = useSelect(
( select ) => select( blocksStore ).getCategories(),
[]
);

return (
<Button
onClick={ () => {
// Add a custom category to the existing list.
setCategories( [
...blockCategories,
{ title: 'Custom Category', slug: 'custom-category' },
] );
} }
>
{ __( 'Add a new custom block category' ) }
</Button>
);
};
```

_Parameters_

- _categories_ `WPBlockCategory[]`: Block categories.
Expand All @@ -774,6 +865,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 +895,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 @@ -849,6 +968,26 @@ _Returns_

Unregisters a block style variation for the given block.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { unregisterBlockStyle } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
return (
<Button
onClick={ () => {
unregisterBlockStyle( 'core/quote', 'plain' );
} }
>
{ __( 'Remove the "Plain" block style for core/quote' ) }
</Button>
);
};
```

_Parameters_

- _blockName_ `string`: Name of block (example: “core/latest-posts”).
Expand All @@ -858,6 +997,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 All @@ -870,6 +1026,26 @@ _Returns_

Unregisters a block variation defined for the given block type.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { unregisterBlockVariation } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
return (
<Button
onClick={ () => {
unregisterBlockVariation( 'core/embed', 'youtube' );
} }
>
{ __( 'Remove the YouTube variation from core/embed' ) }
</Button>
);
};
```

_Parameters_

- _blockName_ `string`: Name of the block (example: “core/columns”).
Expand All @@ -879,6 +1055,26 @@ _Parameters_

Updates a category.

_Usage_

```js
import { __ } from '@wordpress/i18n';
import { updateCategory } from '@wordpress/blocks';
import { Button } from '@wordpress/components';

const ExampleComponent = () => {
return (
<Button
onClick={ () => {
updateCategory( 'text', { title: __( 'Written Word' ) } );
} }
>
{ __( 'Update Text category title' ) }
</Button>
);
};
```

_Parameters_

- _slug_ `string`: Block category slug.
Expand Down
52 changes: 52 additions & 0 deletions packages/blocks/src/api/categories.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ import { store as blocksStore } from '../store';

/**
* Returns all the block categories.
* Ignored from documentation as the recommended usage is via useSelect from @wordpress/data.
*
* @ignore
*
* @return {WPBlockCategory[]} Block categories.
*/
Expand All @@ -23,6 +26,36 @@ export function getCategories() {
* Sets the block categories.
*
* @param {WPBlockCategory[]} categories Block categories.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { store as blocksStore, setCategories } from '@wordpress/blocks';
* import { useSelect } from '@wordpress/data';
* import { Button } from '@wordpress/components';
*
* const ExampleComponent = () => {
* // Retrieve the list of current categories.
* const blockCategories = useSelect(
* ( select ) => select( blocksStore ).getCategories(),
* []
* );
*
* return (
* <Button
* onClick={ () => {
* // Add a custom category to the existing list.
* setCategories( [
* ...blockCategories,
* { title: 'Custom Category', slug: 'custom-category' },
* ] );
* } }
* >
* { __( 'Add a new custom block category' ) }
* </Button>
* );
* };
* ```
*/
export function setCategories( categories ) {
dispatch( blocksStore ).setCategories( categories );
Expand All @@ -34,6 +67,25 @@ export function setCategories( categories ) {
* @param {string} slug Block category slug.
* @param {WPBlockCategory} category Object containing the category properties
* that should be updated.
*
* @example
* ```js
* import { __ } from '@wordpress/i18n';
* import { updateCategory } from '@wordpress/blocks';
* import { Button } from '@wordpress/components';
*
* const ExampleComponent = () => {
* return (
* <Button
* onClick={ () => {
* updateCategory( 'text', { title: __( 'Written Word' ) } );
* } }
* >
* { __( 'Update Text category title' ) }
* </Button>
* ) ;
* };
* ```
*/
export function updateCategory( slug, category ) {
dispatch( blocksStore ).updateCategory( slug, category );
Expand Down
Loading