Skip to content

Commit

Permalink
[Documentation] Adding @example entries to the public API exposed i…
Browse files Browse the repository at this point in the history 
…n `core/blocks` (#42745)

* Adding a simple example and reference to the Create a block tutorial.

* Add examples for registerBlockCollection and unregisterBlockType.

* Add examples for setDefaultBlockName and setGroupingBlockName.

* Add example for setCategory.

* Add example for updateCategory and @ignore getCategories in favor of hook usage.

* Add examples for registerBlockStyle and unregisterBlockStyle.

* Add examples for registerBlockVariation, unregisterBlockVariation, and @ignore getBlockVariations.

* Add example for unregisterBlockCollection.

* Update registerBlockType example to remove i18n in save property.

* Update packages/blocks/README.md

Co-authored-by: Greg Ziółkowski <[email protected]>

* Updates per code review.

* Rebuild docs to include the committed suggestion.

Co-authored-by: Greg Ziółkowski <[email protected]>
  • Loading branch information
@ryanwelcher @gziolo
ryanwelcher and gziolo authored Aug 8, 2022
1 parent 6ecb4c7 commit a4a8751
Show file tree
Hide file tree
Showing 3 changed files with 448 additions and 21 deletions.
242 changes: 221 additions & 21 deletions packages/blocks/README.md
View file
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>,
} );
```
_Parameters_
- _namespace_ `string`: The namespace to group blocks by in the inserter; corresponds to the block namespace.
Expand All @@ -696,6 +694,31 @@ _Parameters_
Registers a new block style variation for the given block.
For more information on connecting the styles with CSS [the official documentation](/docs/reference-guides/block-api/block-styles.md#styles)
_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' ),
} );
} }
>
{ __( 'Add a new block style for core/quote' ) }
</Button>
);
};
```
_Parameters_
- _blockName_ `string`: Name of block (example: “core/latest-posts”).
Expand All @@ -707,6 +730,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 +758,32 @@ _Returns_
Registers a new block variation for the given block type.
For more information on block variations see [the official documentation ](/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 +830,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 +869,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 +899,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' ) }
</Button>
);
};
```
_Parameters_
- _name_ `string`: Block name.
Expand Down Expand Up @@ -849,6 +972,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 +1001,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 +1030,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 +1059,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
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

0 comments on commit a4a8751

Please sign in to comment.