From 40811d47fe30c0576fd0b9a91f8c4a7c924f0521 Mon Sep 17 00:00:00 2001 From: Carlos Bravo <37012961+cbravobernal@users.noreply.github.com> Date: Mon, 30 Sep 2024 15:04:18 +0200 Subject: [PATCH 01/10] Try use select and dispatch instead of registry --- packages/block-editor/src/hooks/use-bindings-attributes.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-editor/src/hooks/use-bindings-attributes.js b/packages/block-editor/src/hooks/use-bindings-attributes.js index fdc617fda20c05..99ab6e240dcc97 100644 --- a/packages/block-editor/src/hooks/use-bindings-attributes.js +++ b/packages/block-editor/src/hooks/use-bindings-attributes.js @@ -201,7 +201,7 @@ export const withBlockBindingSupport = createHigherOrderComponent( const _setAttributes = useCallback( ( nextAttributes ) => { - registry.batch( () => { + registry.batch( ( select, dispatch ) => { if ( ! blockBindings ) { setAttributes( nextAttributes ); return; From 73840b21b56a22382f9fee9e56acff08db37b6d1 Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:04:18 +0200 Subject: [PATCH 02/10] Fix `setValues` --- packages/block-editor/src/hooks/use-bindings-attributes.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-editor/src/hooks/use-bindings-attributes.js b/packages/block-editor/src/hooks/use-bindings-attributes.js index 99ab6e240dcc97..fdc617fda20c05 100644 --- a/packages/block-editor/src/hooks/use-bindings-attributes.js +++ b/packages/block-editor/src/hooks/use-bindings-attributes.js @@ -201,7 +201,7 @@ export const withBlockBindingSupport = createHigherOrderComponent( const _setAttributes = useCallback( ( nextAttributes ) => { - registry.batch( ( select, dispatch ) => { + registry.batch( () => { if ( ! blockBindings ) { setAttributes( nextAttributes ); return; From ba6b920b70b8963a5bbc2f29cffed7305a1a7e19 Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:04:18 +0200 Subject: [PATCH 03/10] Open `useBlockBindingsUtils` --- packages/block-editor/README.md | 32 ++++++++++++++++ packages/block-editor/src/private-apis.js | 2 - .../block-editor/src/utils/block-bindings.js | 37 +++++++++++++++++++ packages/block-editor/src/utils/index.js | 1 + .../components/pattern-overrides-controls.js | 5 +-- 5 files changed, 71 insertions(+), 6 deletions(-) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 75d7e8879572d4..e7b821d219f033 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -839,6 +839,38 @@ _Related_ - +### useBlockBindingsUtils + +Retrieves the existing utils to update the block `bindings` metadata. + +_Usage_ + +```js +import { useBlockBindingsUtils } from '@wordpress/block-editor'; +const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils(); + +updateBlockBindings( { + url: { + source: 'core/post-meta', + args: { + key: 'url_custom_field', + }, + }, + alt: { + source: 'core/post-meta', + args: { + key: 'text_custom_field', + }, + }, +} ); + +removeAllBlockBindings(); +``` + +_Returns_ + +- `?WPBlockBindingsUtils`: Object containing the block bindings utils. + ### useBlockCommands Undocumented declaration. diff --git a/packages/block-editor/src/private-apis.js b/packages/block-editor/src/private-apis.js index 12f477a95a196b..7205bef5798ec1 100644 --- a/packages/block-editor/src/private-apis.js +++ b/packages/block-editor/src/private-apis.js @@ -47,7 +47,6 @@ import { PrivatePublishDateTimePicker } from './components/publish-date-time-pic import useSpacingSizes from './components/spacing-sizes-control/hooks/use-spacing-sizes'; import useBlockDisplayTitle from './components/block-title/use-block-display-title'; import TabbedSidebar from './components/tabbed-sidebar'; -import { useBlockBindingsUtils } from './utils/block-bindings'; /** * Private @wordpress/block-editor APIs. @@ -92,6 +91,5 @@ lock( privateApis, { useBlockDisplayTitle, __unstableBlockStyleVariationOverridesWithConfig, setBackgroundStyleDefaults, - useBlockBindingsUtils, sectionRootClientIdKey, } ); diff --git a/packages/block-editor/src/utils/block-bindings.js b/packages/block-editor/src/utils/block-bindings.js index b3daf4f4b36b43..6af3cc90eb5f5e 100644 --- a/packages/block-editor/src/utils/block-bindings.js +++ b/packages/block-editor/src/utils/block-bindings.js @@ -13,6 +13,43 @@ function isObjectEmpty( object ) { return ! object || Object.keys( object ).length === 0; } +/** + * Contains utils to update the block `bindings` metadata. + * + * @typedef {Object} WPBlockBindingsUtils + * + * @property {Function} updateBlockBindings Updates the value of the bindings connected to block attributes. + * @property {Function} removeAllBlockBindings Removes the bindings property of the `metadata` attribute. + */ + +/** + * Retrieves the existing utils to update the block `bindings` metadata. + * + * @return {?WPBlockBindingsUtils} Object containing the block bindings utils. + * + * @example + * ```js + * import { useBlockBindingsUtils } from '@wordpress/block-editor' + * const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils(); + * + * updateBlockBindings( { + * url: { + * source: 'core/post-meta', + * args: { + * key: 'url_custom_field', + * }, + * }, + * alt: { + * source: 'core/post-meta', + * args: { + * key: 'text_custom_field', + * }, + * } + * } ); + * + * removeAllBlockBindings(); + * ``` + */ export function useBlockBindingsUtils() { const { clientId } = useBlockEditContext(); const { updateBlockAttributes } = useDispatch( blockEditorStore ); diff --git a/packages/block-editor/src/utils/index.js b/packages/block-editor/src/utils/index.js index 6f53ba585e5ecb..1b5aa769a13b28 100644 --- a/packages/block-editor/src/utils/index.js +++ b/packages/block-editor/src/utils/index.js @@ -1,2 +1,3 @@ export { default as transformStyles } from './transform-styles'; export { default as getPxFromCssUnit } from './get-px-from-css-unit'; +export { useBlockBindingsUtils } from './block-bindings'; diff --git a/packages/patterns/src/components/pattern-overrides-controls.js b/packages/patterns/src/components/pattern-overrides-controls.js index 28dd8788a390c6..5207348c7bd7c6 100644 --- a/packages/patterns/src/components/pattern-overrides-controls.js +++ b/packages/patterns/src/components/pattern-overrides-controls.js @@ -4,7 +4,7 @@ import { useState, useId } from '@wordpress/element'; import { InspectorControls, - privateApis as blockEditorPrivateApis, + useBlockBindingsUtils, } from '@wordpress/block-editor'; import { BaseControl, Button } from '@wordpress/components'; import { __ } from '@wordpress/i18n'; @@ -17,9 +17,6 @@ import { AllowOverridesModal, DisallowOverridesModal, } from './allow-overrides-modal'; -import { unlock } from '../lock-unlock'; - -const { useBlockBindingsUtils } = unlock( blockEditorPrivateApis ); function PatternOverridesControls( { attributes, From 3d36af78facd50b5f9b34cbb45d6e8e79ef3b57b Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:04:18 +0200 Subject: [PATCH 04/10] Open registration APIs --- .../src/components/rich-text/index.js | 4 +- .../block-editor/src/hooks/block-bindings.js | 10 +-- packages/block-library/src/block/edit.js | 3 +- packages/block-library/src/button/edit.js | 9 ++- packages/block-library/src/image/edit.js | 9 ++- packages/block-library/src/image/image.js | 3 +- packages/blocks/README.md | 66 +++++++++++++++++++ packages/blocks/src/api/index.js | 18 ++--- packages/blocks/src/api/registration.js | 2 +- .../e2e-tests/plugins/block-bindings/index.js | 8 +-- packages/editor/src/bindings/api.js | 3 +- .../editor/src/hooks/pattern-overrides.js | 3 +- 12 files changed, 91 insertions(+), 47 deletions(-) diff --git a/packages/block-editor/src/components/rich-text/index.js b/packages/block-editor/src/components/rich-text/index.js index 26cd2a97b515ed..8a5d99a7eb9f0a 100644 --- a/packages/block-editor/src/components/rich-text/index.js +++ b/packages/block-editor/src/components/rich-text/index.js @@ -20,7 +20,7 @@ import { removeFormat, } from '@wordpress/rich-text'; import { Popover } from '@wordpress/components'; -import { store as blocksStore } from '@wordpress/blocks'; +import { getBlockBindingsSource } from '@wordpress/blocks'; import deprecated from '@wordpress/deprecated'; import { __, sprintf } from '@wordpress/i18n'; @@ -39,7 +39,6 @@ import FormatEdit from './format-edit'; import { getAllowedFormats } from './utils'; import { Content, valueToHTMLString } from './content'; import { withDeprecations } from './with-deprecations'; -import { unlock } from '../../lock-unlock'; import { canBindBlock } from '../../hooks/use-bindings-attributes'; import BlockContext from '../block-context'; @@ -175,7 +174,6 @@ export function RichTextWrapper( } const relatedBinding = blockBindings[ identifier ]; - const { getBlockBindingsSource } = unlock( select( blocksStore ) ); const blockBindingsSource = getBlockBindingsSource( relatedBinding.source ); diff --git a/packages/block-editor/src/hooks/block-bindings.js b/packages/block-editor/src/hooks/block-bindings.js index c258927f2fd6dc..5c002613831ce1 100644 --- a/packages/block-editor/src/hooks/block-bindings.js +++ b/packages/block-editor/src/hooks/block-bindings.js @@ -2,7 +2,10 @@ * WordPress dependencies */ import { __ } from '@wordpress/i18n'; -import { privateApis as blocksPrivateApis } from '@wordpress/blocks'; +import { + getBlockBindingsSource, + getBlockBindingsSources, +} from '@wordpress/blocks'; import { __experimentalItemGroup as ItemGroup, __experimentalItem as Item, @@ -47,7 +50,6 @@ const useToolsPanelDropdownMenuProps = () => { }; function BlockBindingsPanelDropdown( { fieldsList, attribute, binding } ) { - const { getBlockBindingsSources } = unlock( blocksPrivateApis ); const registeredSources = getBlockBindingsSources(); const { updateBlockBindings } = useBlockBindingsUtils(); const currentKey = binding?.args?.key; @@ -96,8 +98,7 @@ function BlockBindingsPanelDropdown( { fieldsList, attribute, binding } ) { function BlockBindingsAttribute( { attribute, binding, fieldsList } ) { const { source: sourceName, args } = binding || {}; - const sourceProps = - unlock( blocksPrivateApis ).getBlockBindingsSource( sourceName ); + const sourceProps = getBlockBindingsSource( sourceName ); const isSourceInvalid = ! sourceProps; return ( @@ -200,7 +201,6 @@ export const BlockBindingsPanel = ( { name: blockName, metadata } ) => { if ( ! bindableAttributes || bindableAttributes.length === 0 ) { return EMPTY_OBJECT; } - const { getBlockBindingsSources } = unlock( blocksPrivateApis ); const registeredSources = getBlockBindingsSources(); Object.entries( registeredSources ).forEach( ( [ sourceName, { getFieldsList, usesContext } ] ) => { diff --git a/packages/block-library/src/block/edit.js b/packages/block-library/src/block/edit.js index 5c90361e6bb435..104b07157cba74 100644 --- a/packages/block-library/src/block/edit.js +++ b/packages/block-library/src/block/edit.js @@ -32,7 +32,7 @@ import { InnerBlocks, } from '@wordpress/block-editor'; import { privateApis as patternsPrivateApis } from '@wordpress/patterns'; -import { store as blocksStore } from '@wordpress/blocks'; +import { getBlockBindingsSource } from '@wordpress/blocks'; /** * Internal dependencies @@ -196,7 +196,6 @@ function ReusableBlockEdit( { ( select ) => { const { getBlocks, getSettings, getBlockEditingMode } = select( blockEditorStore ); - const { getBlockBindingsSource } = unlock( select( blocksStore ) ); // For editing link to the site editor if the theme and user permissions support it. return { innerBlocks: getBlocks( patternClientId ), diff --git a/packages/block-library/src/button/edit.js b/packages/block-library/src/button/edit.js index d7b8e6486c3c66..3539fd54f4eece 100644 --- a/packages/block-library/src/button/edit.js +++ b/packages/block-library/src/button/edit.js @@ -9,7 +9,6 @@ import clsx from 'clsx'; import { NEW_TAB_TARGET, NOFOLLOW_REL } from './constants'; import { getUpdatedLinkAttributes } from './get-updated-link-attributes'; import removeAnchorTag from '../utils/remove-anchor-tag'; -import { unlock } from '../lock-unlock'; /** * WordPress dependencies @@ -45,7 +44,7 @@ import { createBlock, cloneBlock, getDefaultBlockName, - store as blocksStore, + getBlockBindingsSource, } from '@wordpress/blocks'; import { useMergeRefs, useRefEffect } from '@wordpress/compose'; import { useSelect, useDispatch } from '@wordpress/data'; @@ -240,9 +239,9 @@ function ButtonEdit( props ) { return {}; } - const blockBindingsSource = unlock( - select( blocksStore ) - ).getBlockBindingsSource( metadata?.bindings?.url?.source ); + const blockBindingsSource = getBlockBindingsSource( + metadata?.bindings?.url?.source + ); return { lockUrlControls: diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js index d44dc73abfd855..360c4b8e6127b8 100644 --- a/packages/block-library/src/image/edit.js +++ b/packages/block-library/src/image/edit.js @@ -7,7 +7,7 @@ import clsx from 'clsx'; * WordPress dependencies */ import { isBlobURL, createBlobURL } from '@wordpress/blob'; -import { store as blocksStore, createBlock } from '@wordpress/blocks'; +import { createBlock, getBlockBindingsSource } from '@wordpress/blocks'; import { Placeholder } from '@wordpress/components'; import { useDispatch, useSelect } from '@wordpress/data'; import { @@ -28,7 +28,6 @@ import { useResizeObserver } from '@wordpress/compose'; /** * Internal dependencies */ -import { unlock } from '../lock-unlock'; import { useUploadMediaFromBlobURL } from '../utils/hooks'; import Image from './image'; import { isValidFileType } from './utils'; @@ -372,9 +371,9 @@ export function ImageEdit( { return {}; } - const blockBindingsSource = unlock( - select( blocksStore ) - ).getBlockBindingsSource( metadata?.bindings?.url?.source ); + const blockBindingsSource = getBlockBindingsSource( + metadata?.bindings?.url?.source + ); return { lockUrlControls: diff --git a/packages/block-library/src/image/image.js b/packages/block-library/src/image/image.js index 1673d36e463d5a..89bf31f92664b9 100644 --- a/packages/block-library/src/image/image.js +++ b/packages/block-library/src/image/image.js @@ -34,7 +34,7 @@ import { useEffect, useMemo, useState, useRef } from '@wordpress/element'; import { __, _x, sprintf, isRTL } from '@wordpress/i18n'; import { DOWN } from '@wordpress/keycodes'; import { getFilename } from '@wordpress/url'; -import { switchToBlockType, store as blocksStore } from '@wordpress/blocks'; +import { getBlockBindingsSource, switchToBlockType } from '@wordpress/blocks'; import { crop, overlayText, upload } from '@wordpress/icons'; import { store as noticesStore } from '@wordpress/notices'; import { store as coreStore } from '@wordpress/core-data'; @@ -476,7 +476,6 @@ export default function Image( { if ( ! isSingleSelected ) { return {}; } - const { getBlockBindingsSource } = unlock( select( blocksStore ) ); const { url: urlBinding, alt: altBinding, diff --git a/packages/blocks/README.md b/packages/blocks/README.md index b607286f1e73c7..1aa4aeb67ad046 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -115,6 +115,26 @@ _Returns_ - `string[]`: The attribute names that have the provided role. +### getBlockBindingsSource + +Returns a registered block bindings source. + +_Parameters_ + +- _name_ `string`: Block bindings source name. + +_Returns_ + +- `?Object`: Block bindings source. + +### getBlockBindingsSources + +Returns all registered block bindings sources. + +_Returns_ + +- `Array`: Block bindings sources. + ### getBlockContent Given a block object, returns the Block's Inner HTML markup. @@ -492,6 +512,36 @@ _Returns_ - `Array`: A list of blocks. +### registerBlockBindingsSource + +Registers a new block bindings source with an object defining its behavior. Once registered, the source is available to be connected to the supported block attributes. + +_Usage_ + +```js +import { _x } from '@wordpress/i18n'; +import { registerBlockBindingsSource } from '@wordpress/blocks'; + +registerBlockBindingsSource( { + name: 'plugin/my-custom-source', + label: _x( 'My Custom Source', 'block bindings source' ), + usesContext: [ 'postType' ], + getValues: () => getSourceValues(), + setValues: () => updateMyCustomValuesInBatch(), + canUserEditValue: () => true, +} ); +``` + +_Parameters_ + +- _source_ `Object`: Properties of the source to be registered. +- _source.name_ `string`: The unique and machine-readable name. +- _source.label_ `[string]`: Human-readable label. +- _source.usesContext_ `[Array]`: Array of context needed by the source only in the editor. +- _source.getValues_ `[Function]`: Function to get the values from the source. +- _source.setValues_ `[Function]`: Function to update multiple values connected to the source. +- _source.canUserEditValue_ `[Function]`: Function to determine if the user can edit the value. + ### registerBlockCollection Registers a new block collection to group blocks in the same namespace in the inserter. @@ -793,6 +843,22 @@ _Returns_ - `Array`: Updated Block list. +### unregisterBlockBindingsSource + +Unregisters a block bindings source + +_Usage_ + +```js +import { unregisterBlockBindingsSource } from '@wordpress/blocks'; + +unregisterBlockBindingsSource( 'plugin/my-custom-source' ); +``` + +_Parameters_ + +- _name_ `string`: The name of the block bindings source to unregister. + ### unregisterBlockStyle Unregisters a block style for the given block. diff --git a/packages/blocks/src/api/index.js b/packages/blocks/src/api/index.js index e23f347fe4fee8..0b38b8e29e68a0 100644 --- a/packages/blocks/src/api/index.js +++ b/packages/blocks/src/api/index.js @@ -2,12 +2,6 @@ * Internal dependencies */ import { lock } from '../lock-unlock'; -import { - registerBlockBindingsSource, - unregisterBlockBindingsSource, - getBlockBindingsSource, - getBlockBindingsSources, -} from './registration'; import { isUnmodifiedBlockContent } from './utils'; // The blocktype is the most important concept within the block API. It defines @@ -147,6 +141,10 @@ export { unregisterBlockStyle, registerBlockVariation, unregisterBlockVariation, + registerBlockBindingsSource, + unregisterBlockBindingsSource, + getBlockBindingsSource, + getBlockBindingsSources, } from './registration'; export { isUnmodifiedBlock, @@ -179,10 +177,4 @@ export { } from './constants'; export const privateApis = {}; -lock( privateApis, { - registerBlockBindingsSource, - unregisterBlockBindingsSource, - getBlockBindingsSource, - getBlockBindingsSources, - isUnmodifiedBlockContent, -} ); +lock( privateApis, { isUnmodifiedBlockContent } ); diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index b0f5ae350759f0..497f4a6db095dd 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -774,7 +774,6 @@ export const unregisterBlockVariation = ( blockName, variationName ) => { * @param {Function} [source.getValues] Function to get the values from the source. * @param {Function} [source.setValues] Function to update multiple values connected to the source. * @param {Function} [source.canUserEditValue] Function to determine if the user can edit the value. - * @param {Function} [source.getFieldsList] Function to get the lists of fields to expose in the connections panel. * * @example * ```js @@ -784,6 +783,7 @@ export const unregisterBlockVariation = ( blockName, variationName ) => { * registerBlockBindingsSource( { * name: 'plugin/my-custom-source', * label: _x( 'My Custom Source', 'block bindings source' ), + * usesContext: [ 'postType' ], * getValues: () => getSourceValues(), * setValues: () => updateMyCustomValuesInBatch(), * canUserEditValue: () => true, diff --git a/packages/e2e-tests/plugins/block-bindings/index.js b/packages/e2e-tests/plugins/block-bindings/index.js index 0bfc49041647de..c31502631307d0 100644 --- a/packages/e2e-tests/plugins/block-bindings/index.js +++ b/packages/e2e-tests/plugins/block-bindings/index.js @@ -1,10 +1,4 @@ -const { unlock } = - wp.privateApis.__dangerousOptInToUnstableAPIsOnlyForCoreModules( - 'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.', - '@wordpress/blocks' - ); - -const { registerBlockBindingsSource } = unlock( wp.blocks.privateApis ); +const { registerBlockBindingsSource } = wp.blocks; const { fieldsList } = window.testingBindings || {}; const getValues = ( { bindings } ) => { diff --git a/packages/editor/src/bindings/api.js b/packages/editor/src/bindings/api.js index 2cfed5168a143e..84003fab7eaf7b 100644 --- a/packages/editor/src/bindings/api.js +++ b/packages/editor/src/bindings/api.js @@ -2,8 +2,8 @@ * WordPress dependencies */ import { - privateApis as blocksPrivateApis, store as blocksStore, + registerBlockBindingsSource, } from '@wordpress/blocks'; import { dispatch } from '@wordpress/data'; @@ -25,7 +25,6 @@ import { unlock } from '../lock-unlock'; * ``` */ export function registerCoreBlockBindingsSources() { - const { registerBlockBindingsSource } = unlock( blocksPrivateApis ); registerBlockBindingsSource( patternOverrides ); registerBlockBindingsSource( postMeta ); } diff --git a/packages/editor/src/hooks/pattern-overrides.js b/packages/editor/src/hooks/pattern-overrides.js index 6f81f368351f38..8882856a89e0d9 100644 --- a/packages/editor/src/hooks/pattern-overrides.js +++ b/packages/editor/src/hooks/pattern-overrides.js @@ -6,7 +6,7 @@ import { privateApis as patternsPrivateApis } from '@wordpress/patterns'; import { createHigherOrderComponent } from '@wordpress/compose'; import { useBlockEditingMode } from '@wordpress/block-editor'; import { useSelect } from '@wordpress/data'; -import { store as blocksStore } from '@wordpress/blocks'; +import { getBlockBindingsSource } from '@wordpress/blocks'; /** * Internal dependencies @@ -58,7 +58,6 @@ function ControlsWithStoreSubscription( props ) { const blockEditingMode = useBlockEditingMode(); const { hasPatternOverridesSource, isEditingSyncedPattern } = useSelect( ( select ) => { - const { getBlockBindingsSource } = unlock( select( blocksStore ) ); const { getCurrentPostType, getEditedPostAttribute } = select( editorStore ); From 1fbfde4a267b205df6a39586316d5cb9b2d53d0d Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:04:18 +0200 Subject: [PATCH 05/10] Restrict `getFieldsList` API --- packages/blocks/src/store/reducer.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/blocks/src/store/reducer.js b/packages/blocks/src/store/reducer.js index 4aa0b922e090fd..7c7fb4763a1cb6 100644 --- a/packages/blocks/src/store/reducer.js +++ b/packages/blocks/src/store/reducer.js @@ -393,6 +393,13 @@ function getMergedUsesContext( existingUsesContext = [], newUsesContext = [] ) { export function blockBindingsSources( state = {}, action ) { switch ( action.type ) { case 'ADD_BLOCK_BINDINGS_SOURCE': + // Only open this API in Gutenberg and for `core/post-meta` for the moment. + let getFieldsList; + if ( globalThis.IS_GUTENBERG_PLUGIN ) { + getFieldsList = action.getFieldsList; + } else if ( action.name === 'core/post-meta' ) { + getFieldsList = action.getFieldsList; + } return { ...state, [ action.name ]: { @@ -407,7 +414,7 @@ export function blockBindingsSources( state = {}, action ) { // Only set `canUserEditValue` if `setValues` is also defined. canUserEditValue: action.setValues && action.canUserEditValue, - getFieldsList: action.getFieldsList, + getFieldsList, }, }; case 'ADD_BOOTSTRAPPED_BLOCK_BINDINGS_SOURCE': From f3a9e4d4575f59a190dddfdb26d09e3db52dfb24 Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:13:32 +0200 Subject: [PATCH 06/10] Update `useBlockBindingsUtils` docs --- packages/block-editor/README.md | 12 +++++++++++- packages/block-editor/src/utils/block-bindings.js | 12 +++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index e7b821d219f033..32ba4598c4f92d 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -841,7 +841,12 @@ _Related_ ### useBlockBindingsUtils -Retrieves the existing utils to update the block `bindings` metadata. +Retrieves the existing utils needed to update the block `bindings` metadata. They can be used to create, modify, or remove connections from the existing block attributes. + +It contains the following utils: + +- `updateBlockBindings`: Updates the value of the bindings connected to block attributes. It can be used to remove a specific binding by setting the value to `undefined`. +- `removeAllBlockBindings`: Removes the bindings property of the `metadata` attribute. _Usage_ @@ -849,6 +854,7 @@ _Usage_ import { useBlockBindingsUtils } from '@wordpress/block-editor'; const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils(); +// Update url and alt attributes. updateBlockBindings( { url: { source: 'core/post-meta', @@ -864,6 +870,10 @@ updateBlockBindings( { }, } ); +// Remove binding from url attribute. +updateBlockBindings( { url: undefined } ); + +// Remove bindings from all attributes. removeAllBlockBindings(); ``` diff --git a/packages/block-editor/src/utils/block-bindings.js b/packages/block-editor/src/utils/block-bindings.js index 6af3cc90eb5f5e..8c3c92ff5e2456 100644 --- a/packages/block-editor/src/utils/block-bindings.js +++ b/packages/block-editor/src/utils/block-bindings.js @@ -23,7 +23,12 @@ function isObjectEmpty( object ) { */ /** - * Retrieves the existing utils to update the block `bindings` metadata. + * Retrieves the existing utils needed to update the block `bindings` metadata. + * They can be used to create, modify, or remove connections from the existing block attributes. + * + * It contains the following utils: + * - `updateBlockBindings`: Updates the value of the bindings connected to block attributes. It can be used to remove a specific binding by setting the value to `undefined`. + * - `removeAllBlockBindings`: Removes the bindings property of the `metadata` attribute. * * @return {?WPBlockBindingsUtils} Object containing the block bindings utils. * @@ -32,6 +37,7 @@ function isObjectEmpty( object ) { * import { useBlockBindingsUtils } from '@wordpress/block-editor' * const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils(); * + * // Update url and alt attributes. * updateBlockBindings( { * url: { * source: 'core/post-meta', @@ -47,6 +53,10 @@ function isObjectEmpty( object ) { * } * } ); * + * // Remove binding from url attribute. + * updateBlockBindings( { url: undefined } ); + * + * // Remove bindings from all attributes. * removeAllBlockBindings(); * ``` */ From a1821c798e037737bc00ff9ff364b55e4bcce00a Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:16:00 +0200 Subject: [PATCH 07/10] Update register/unregister bindings docs --- packages/blocks/README.md | 4 ++-- packages/blocks/src/api/registration.js | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 1aa4aeb67ad046..9febd47d4aa29a 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -117,7 +117,7 @@ _Returns_ ### getBlockBindingsSource -Returns a registered block bindings source. +Returns a registered block bindings source by its name. _Parameters_ @@ -845,7 +845,7 @@ _Returns_ ### unregisterBlockBindingsSource -Unregisters a block bindings source +Unregisters a block bindings source by providing its name. _Usage_ diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index 497f4a6db095dd..489dd5ccd81680 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -903,7 +903,7 @@ export const registerBlockBindingsSource = ( source ) => { }; /** - * Unregisters a block bindings source + * Unregisters a block bindings source by providing its name. * * @param {string} name The name of the block bindings source to unregister. * @@ -924,7 +924,7 @@ export function unregisterBlockBindingsSource( name ) { } /** - * Returns a registered block bindings source. + * Returns a registered block bindings source by its name. * * @param {string} name Block bindings source name. * From 9de4c6b61a6c41eea92bb5a8d6030c0018cfd36c Mon Sep 17 00:00:00 2001 From: Mario Santos <34552881+SantosGuillamot@users.noreply.github.com> Date: Mon, 30 Sep 2024 15:19:52 +0200 Subject: [PATCH 08/10] Simplify API functions examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Greg Ziółkowski --- packages/blocks/src/api/registration.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index 489dd5ccd81680..ae863b542fc748 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -784,8 +784,8 @@ export const unregisterBlockVariation = ( blockName, variationName ) => { * name: 'plugin/my-custom-source', * label: _x( 'My Custom Source', 'block bindings source' ), * usesContext: [ 'postType' ], - * getValues: () => getSourceValues(), - * setValues: () => updateMyCustomValuesInBatch(), + * getValues: getSourceValues, + * setValues: updateMyCustomValuesInBatch, * canUserEditValue: () => true, * } ); * ``` From a2872b5ac59b4b7f4d6ed26b79ddff792001cfd5 Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 15:29:53 +0200 Subject: [PATCH 09/10] Update docs --- packages/blocks/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 9febd47d4aa29a..7d6c321e5783fb 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -526,8 +526,8 @@ registerBlockBindingsSource( { name: 'plugin/my-custom-source', label: _x( 'My Custom Source', 'block bindings source' ), usesContext: [ 'postType' ], - getValues: () => getSourceValues(), - setValues: () => updateMyCustomValuesInBatch(), + getValues: getSourceValues, + setValues: updateMyCustomValuesInBatch, canUserEditValue: () => true, } ); ``` From a5792ef501c8945d5f0b2537cb2d8a4771606d18 Mon Sep 17 00:00:00 2001 From: Mario Santos Date: Mon, 30 Sep 2024 18:50:37 +0200 Subject: [PATCH 10/10] Update comments --- packages/block-editor/src/utils/block-bindings.js | 4 ++-- packages/blocks/README.md | 10 +++++----- packages/blocks/src/api/registration.js | 10 +++++----- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/block-editor/src/utils/block-bindings.js b/packages/block-editor/src/utils/block-bindings.js index 8c3c92ff5e2456..db4de9d39cb253 100644 --- a/packages/block-editor/src/utils/block-bindings.js +++ b/packages/block-editor/src/utils/block-bindings.js @@ -44,13 +44,13 @@ function isObjectEmpty( object ) { * args: { * key: 'url_custom_field', * }, - * }, + * }, * alt: { * source: 'core/post-meta', * args: { * key: 'text_custom_field', * }, - * } + * }, * } ); * * // Remove binding from url attribute. diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 7d6c321e5783fb..c5a754f88d4929 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -536,11 +536,11 @@ _Parameters_ - _source_ `Object`: Properties of the source to be registered. - _source.name_ `string`: The unique and machine-readable name. -- _source.label_ `[string]`: Human-readable label. -- _source.usesContext_ `[Array]`: Array of context needed by the source only in the editor. -- _source.getValues_ `[Function]`: Function to get the values from the source. -- _source.setValues_ `[Function]`: Function to update multiple values connected to the source. -- _source.canUserEditValue_ `[Function]`: Function to determine if the user can edit the value. +- _source.label_ `[string]`: Human-readable label. Optional when it is defined in the server. +- _source.usesContext_ `[Array]`: Optional array of context needed by the source only in the editor. +- _source.getValues_ `[Function]`: Optional function to get the values from the source. +- _source.setValues_ `[Function]`: Optional function to update multiple values connected to the source. +- _source.canUserEditValue_ `[Function]`: Optional function to determine if the user can edit the value. ### registerBlockCollection diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index ae863b542fc748..f7d85cd816c9df 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -769,11 +769,11 @@ export const unregisterBlockVariation = ( blockName, variationName ) => { * * @param {Object} source Properties of the source to be registered. * @param {string} source.name The unique and machine-readable name. - * @param {string} [source.label] Human-readable label. - * @param {Array} [source.usesContext] Array of context needed by the source only in the editor. - * @param {Function} [source.getValues] Function to get the values from the source. - * @param {Function} [source.setValues] Function to update multiple values connected to the source. - * @param {Function} [source.canUserEditValue] Function to determine if the user can edit the value. + * @param {string} [source.label] Human-readable label. Optional when it is defined in the server. + * @param {Array} [source.usesContext] Optional array of context needed by the source only in the editor. + * @param {Function} [source.getValues] Optional function to get the values from the source. + * @param {Function} [source.setValues] Optional function to update multiple values connected to the source. + * @param {Function} [source.canUserEditValue] Optional function to determine if the user can edit the value. * * @example * ```js