diff --git a/docs/how-to-guides/backward-compatibility/deprecations.md b/docs/how-to-guides/backward-compatibility/deprecations.md index df0b5af1d781e..d2839d21a7b06 100644 --- a/docs/how-to-guides/backward-compatibility/deprecations.md +++ b/docs/how-to-guides/backward-compatibility/deprecations.md @@ -2,6 +2,10 @@ For features included in the Gutenberg plugin, the deprecation policy is intended to support backward compatibility for two minor plugin releases, when possible. Features and code included in a stable release of WordPress are not included in this deprecation timeline, and are instead subject to the [versioning policies of the WordPress project](https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/). The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version. +## 11.0.0 + +- `wp.blocks.registerBlockTypeFromMetadata` method has been removed. Use `wp.blocks.registerBlockType` method instead. + ## 10.3.0 - Passing a tuple of components with `as` prop to `ActionItem.Slot` component is no longer supported. Please pass a component with `as` prop instead. Example: diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md index 6a4160906ba3b..8af6047da2814 100644 --- a/docs/reference-guides/block-api/block-metadata.md +++ b/docs/reference-guides/block-api/block-metadata.md @@ -470,16 +470,16 @@ Implementation follows the existing [get_plugin_data](https://codex.wordpress.or ### JavaScript -In JavaScript, you need to use `registerBlockTypeFromMetadata` method from `@wordpress/blocks` package to process loaded block metadata. All localized properties get automatically wrapped in `_x` (from `@wordpress/i18n` package) function calls similar to how it works in PHP. +In JavaScript, you can use `registerBlockType` method from `@wordpress/blocks` package and pass the metadata object loaded from `block.json` as the first param. All localized properties get automatically wrapped in `_x` (from `@wordpress/i18n` package) function calls similar to how it works in PHP. **Example:** ```js -import { registerBlockTypeFromMetadata } from '@wordpress/blocks'; +import { registerBlockType } from '@wordpress/blocks'; import Edit from './edit'; import metadata from './block.json'; -registerBlockTypeFromMetadata( metadata, { +registerBlockType( metadata, { edit: Edit, // ...other client-side settings } ); diff --git a/packages/block-library/src/index.js b/packages/block-library/src/index.js index 7cbfae9b8c709..6f0ebe50e8fe6 100644 --- a/packages/block-library/src/index.js +++ b/packages/block-library/src/index.js @@ -4,7 +4,7 @@ import '@wordpress/core-data'; import '@wordpress/block-editor'; import { - registerBlockTypeFromMetadata, + registerBlockType, setDefaultBlockName, setFreeformContentHandlerName, setUnregisteredTypeHandlerName, @@ -105,7 +105,7 @@ const registerBlock = ( block ) => { return; } const { metadata, settings, name } = block; - registerBlockTypeFromMetadata( { name, ...metadata }, settings ); + registerBlockType( { name, ...metadata }, settings ); }; /** diff --git a/packages/block-library/src/index.native.js b/packages/block-library/src/index.native.js index 0dffcb66269c1..538b1027fdd91 100644 --- a/packages/block-library/src/index.native.js +++ b/packages/block-library/src/index.native.js @@ -10,7 +10,6 @@ import { sortBy } from 'lodash'; import { hasBlockSupport, registerBlockType, - registerBlockTypeFromMetadata, setDefaultBlockName, setFreeformContentHandlerName, setUnregisteredTypeHandlerName, @@ -128,7 +127,7 @@ const registerBlock = ( block ) => { return; } const { metadata, settings, name } = block; - registerBlockTypeFromMetadata( + registerBlockType( { name, ...metadata, diff --git a/packages/blocks/CHANGELOG.md b/packages/blocks/CHANGELOG.md index 17133cb68f09a..019a43284040f 100644 --- a/packages/blocks/CHANGELOG.md +++ b/packages/blocks/CHANGELOG.md @@ -2,6 +2,14 @@ ## Unreleased +### New API + +- `registerBlockType` method can be used to register a block type using the metadata loaded from `block.json` file ([#32030](https://github.com/WordPress/gutenberg/pull/32030)). + +### Deprecations + +- `registerBlockTypeFromMetadata` was deprecated in favor of `registerBlockType` that support now the same functionality ([#32030](https://github.com/WordPress/gutenberg/pull/32030)). + ## 9.0.0 (2021-05-14) ### Breaking Changes diff --git a/packages/blocks/README.md b/packages/blocks/README.md index c97d11973aea1..dd51909dedfd4 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -706,7 +706,7 @@ editor interface where blocks are implemented. _Parameters_ -- _name_ `string`: Block name. +- _blockNameOrMetadata_ `string|Object`: Block type name or its metadata. - _settings_ `Object`: Block settings. _Returns_ @@ -715,18 +715,13 @@ _Returns_ # **registerBlockTypeFromMetadata** -Registers a new block provided from metadata stored in `block.json` file. -It uses `registerBlockType` internally. +> **Deprecated** Use `registerBlockType` instead. -_Related_ - -- registerBlockType +Registers a new block provided from metadata stored in `block.json` file. _Parameters_ - _metadata_ `Object`: Block metadata loaded from `block.json`. -- _metadata.name_ `string`: Block name. -- _metadata.textdomain_ `string`: Textdomain to use with translations. - _additionalSettings_ `Object`: Additional block settings. _Returns_ diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index b1f62fe4ee9cb..bd55ab95d60f4 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -22,6 +22,7 @@ import { /** * WordPress dependencies */ +import deprecated from '@wordpress/deprecated'; import { applyFilters } from '@wordpress/hooks'; import { select, dispatch } from '@wordpress/data'; import { _x } from '@wordpress/i18n'; @@ -192,18 +193,77 @@ export function unstable__bootstrapServerSideBlockDefinitions( definitions ) { } } +/** + * Gets block settings from metadata loaded from `block.json` file. + * + * @param {Object} metadata Block metadata loaded from `block.json`. + * @param {string} metadata.textdomain Textdomain to use with translations. + * + * @return {Object} Block settings. + */ +function getBlockSettingsFromMetadata( { textdomain, ...metadata } ) { + const allowedFields = [ + 'apiVersion', + 'title', + 'category', + 'parent', + 'icon', + 'description', + 'keywords', + 'attributes', + 'providesContext', + 'usesContext', + 'supports', + 'styles', + 'example', + 'variations', + ]; + + const settings = pick( metadata, allowedFields ); + + if ( textdomain ) { + Object.keys( i18nBlockSchema ).forEach( ( key ) => { + if ( ! settings[ key ] ) { + return; + } + settings[ key ] = translateBlockSettingUsingI18nSchema( + i18nBlockSchema[ key ], + settings[ key ], + textdomain + ); + } ); + } + + return settings; +} + /** * 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. * - * @param {string} name Block name. - * @param {Object} settings Block settings. + * @param {string|Object} blockNameOrMetadata Block type name or its metadata. + * @param {Object} settings Block settings. * * @return {?WPBlock} The block, if it has been successfully registered; * otherwise `undefined`. */ -export function registerBlockType( name, settings ) { +export function registerBlockType( blockNameOrMetadata, settings ) { + const name = isObject( blockNameOrMetadata ) + ? blockNameOrMetadata.name + : blockNameOrMetadata; + + if ( typeof name !== 'string' ) { + console.error( 'Block names must be strings.' ); + return; + } + + if ( isObject( blockNameOrMetadata ) ) { + unstable__bootstrapServerSideBlockDefinitions( { + [ name ]: getBlockSettingsFromMetadata( blockNameOrMetadata ), + } ); + } + settings = { name, icon: blockDefault, @@ -218,10 +278,6 @@ export function registerBlockType( name, settings ) { ...settings, }; - if ( typeof name !== 'string' ) { - console.error( 'Block names must be strings.' ); - return; - } if ( ! /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test( name ) ) { console.error( 'Block names must contain a namespace prefix, include only lowercase alphanumeric characters or dashes, and start with a letter. Example: my-plugin/my-custom-block' @@ -370,59 +426,23 @@ function translateBlockSettingUsingI18nSchema( /** * Registers a new block provided from metadata stored in `block.json` file. - * It uses `registerBlockType` internally. * - * @see registerBlockType + * @deprecated Use `registerBlockType` instead. * * @param {Object} metadata Block metadata loaded from `block.json`. - * @param {string} metadata.name Block name. - * @param {string} metadata.textdomain Textdomain to use with translations. * @param {Object} additionalSettings Additional block settings. * * @return {?WPBlock} The block, if it has been successfully registered; * otherwise `undefined`. */ -export function registerBlockTypeFromMetadata( - { name, textdomain, ...metadata }, - additionalSettings -) { - const allowedFields = [ - 'apiVersion', - 'title', - 'category', - 'parent', - 'icon', - 'description', - 'keywords', - 'attributes', - 'providesContext', - 'usesContext', - 'supports', - 'styles', - 'example', - 'variations', - ]; - - const settings = pick( metadata, allowedFields ); - - if ( textdomain ) { - Object.keys( i18nBlockSchema ).forEach( ( key ) => { - if ( ! settings[ key ] ) { - return; - } - settings[ key ] = translateBlockSettingUsingI18nSchema( - i18nBlockSchema[ key ], - settings[ key ], - textdomain - ); - } ); - } - - unstable__bootstrapServerSideBlockDefinitions( { - [ name ]: settings, +export function registerBlockTypeFromMetadata( metadata, additionalSettings ) { + deprecated( 'wp.blocks.registerBlockTypeFromMetadata', { + since: '10.7', + plugin: 'Gutenberg', + alternative: 'wp.blocks.registerBlockType', + version: '11.0', } ); - - return registerBlockType( name, additionalSettings ); + return registerBlockType( metadata, additionalSettings ); } /** diff --git a/packages/blocks/src/api/test/registration.js b/packages/blocks/src/api/test/registration.js index b8d7c9c413754..49851544dd5ae 100644 --- a/packages/blocks/src/api/test/registration.js +++ b/packages/blocks/src/api/test/registration.js @@ -17,7 +17,6 @@ import { blockDefault as blockIcon } from '@wordpress/icons'; */ import { registerBlockType, - registerBlockTypeFromMetadata, registerBlockCollection, unregisterBlockCollection, unregisterBlockType, @@ -801,12 +800,10 @@ describe( 'blocks', () => { expect( block1.attributes ).not.toEqual( block2.attributes ); } ); } ); - } ); - describe( 'registerBlockTypeFromMetadata', () => { test( 'registers block from metadata', () => { const Edit = () => 'test'; - const block = registerBlockTypeFromMetadata( + const block = registerBlockType( { name: 'test/block-from-metadata', title: 'Block from metadata', @@ -859,7 +856,7 @@ describe( 'blocks', () => { ); const Edit = () => 'test'; - const block = registerBlockTypeFromMetadata( + const block = registerBlockType( { name: 'test/block-from-metadata-i18n', title: 'I18n title from metadata',