Block Bindings: enhance block attribute binding to external sources #58895
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,13 +3,15 @@ | |
| */ | ||
| import { getBlockType, store as blocksStore } from '@wordpress/blocks'; | ||
| import { createHigherOrderComponent } from '@wordpress/compose'; | ||
| import { useSelect, useDispatch } from '@wordpress/data'; | ||
| import { useEffect, useCallback } from '@wordpress/element'; | ||
| import { addFilter } from '@wordpress/hooks'; | ||
| import { RichTextData } from '@wordpress/rich-text'; | ||
|
|
||
| /** | ||
| * Internal dependencies | ||
| */ | ||
| import { store as blockEditorStore } from '../store'; | ||
| import { unlock } from '../lock-unlock'; | ||
|
|
||
| /** @typedef {import('@wordpress/compose').WPHigherOrderComponent} WPHigherOrderComponent */ | ||
|
|
@@ -22,87 +24,216 @@ import { unlock } from '../lock-unlock'; | |
| * @return {WPHigherOrderComponent} Higher-order component. | ||
| */ | ||
|
|
||
| const BLOCK_BINDINGS_ALLOWED_BLOCKS = { | ||
| 'core/paragraph': [ 'content' ], | ||
| 'core/heading': [ 'content' ], | ||
| 'core/image': [ 'url', 'title', 'alt' ], | ||
| 'core/button': [ 'url', 'text', 'linkTarget' ], | ||
| }; | ||
|
|
||
| /** | ||
| * Based on the given block name, | ||
| * check if it is possible to bind the block. | ||
| * | ||
| * @param {string} blockName - The block name. | ||
| * @return {boolean} Whether it is possible to bind the block to sources. | ||
| */ | ||
| export function canBindBlock( blockName ) { | ||
| return blockName in BLOCK_BINDINGS_ALLOWED_BLOCKS; | ||
| } | ||
|
|
||
| /** | ||
| * Based on the given block name and attribute name, | ||
| * check if it is possible to bind the block attribute. | ||
| * | ||
| * @param {string} blockName - The block name. | ||
| * @param {string} attributeName - The attribute name. | ||
| * @return {boolean} Whether it is possible to bind the block attribute. | ||
| */ | ||
| export function canBindAttribute( blockName, attributeName ) { | ||
| return ( | ||
| canBindBlock( blockName ) && | ||
| BLOCK_BINDINGS_ALLOWED_BLOCKS[ blockName ].includes( attributeName ) | ||
| ); | ||
| } | ||
|
|
||
| /** | ||
| * This component is responsible for detecting and | ||
| * propagating data changes from the source to the block. | ||
| * | ||
| * @param {Object} props - The component props. | ||
| * @param {string} props.attrName - The attribute name. | ||
| * @param {Object} props.blockProps - The block props with bound attribute. | ||
| * @param {Object} props.source - Source handler. | ||
| * @param {Object} props.args - The arguments to pass to the source. | ||
| * @return {null} This is a data-handling component. Render nothing. | ||
| */ | ||
| const BindingConnector = ( { args, attrName, blockProps, source } ) => { | ||
| const { placeholder, value: propValue } = source.useSource( | ||
| blockProps, | ||
| args | ||
| ); | ||
|
|
||
| const { setAttributes, name } = blockProps; | ||
| const attrValue = blockProps.attributes[ attrName ]; | ||
|
|
||
| const { syncDerivedUpdates } = unlock( useDispatch( blockEditorStore ) ); | ||
|
|
||
| const updateBoundAttibute = useCallback( | ||
| ( newAttrValue, prevAttrValue ) => { | ||
| /* | ||
| * If the attribute is a RichTextData instance, | ||
| * (core/paragraph, core/heading, core/button, etc.) | ||
| * compare its HTML representation with the new value. | ||
| * | ||
| * To do: it looks like a workaround. | ||
| * Consider improving the attribute and metadata fields types. | ||
| */ | ||
| if ( prevAttrValue instanceof RichTextData ) { | ||
| // Bail early if the Rich Text value is the same. | ||
| if ( prevAttrValue.toHTMLString() === newAttrValue ) { | ||
| return; | ||
| } | ||
|
|
||
| /* | ||
| * To preserve the value type, | ||
| * convert the new value to a RichTextData instance. | ||
| */ | ||
| newAttrValue = RichTextData.fromHTMLString( newAttrValue ); | ||
| } | ||
|
|
||
| if ( prevAttrValue === newAttrValue ) { | ||
| return; | ||
| } | ||
|
|
||
| syncDerivedUpdates( () => { | ||
| setAttributes( { | ||
| [ attrName ]: newAttrValue, | ||
| } ); | ||
| } ); | ||
| }, | ||
| [ attrName, setAttributes, syncDerivedUpdates ] | ||
| ); | ||
|
|
||
| useEffect( () => { | ||
| if ( typeof propValue !== 'undefined' ) { | ||
| updateBoundAttibute( propValue, attrValue ); | ||
|
There was a problem hiding this comment. Could we not use an There was a problem hiding this comment. I'm not sure how doable/easy/convenient it could be, especially considering that we'll have to deal with not only reading but updating the bound attr and external source prop in follow-ups There was a problem hiding this comment. I don't think we can avoid |
||
| } else if ( placeholder ) { | ||
| /* | ||
| * Placeholder fallback. | ||
| * If the attribute is `src` or `href`, | ||
| * a placeholder can't be used because it is not a valid url. | ||
| * Adding this workaround until | ||
| * attributes and metadata fields types are improved and include `url`. | ||
| */ | ||
| const htmlAttribute = | ||
| getBlockType( name ).attributes[ attrName ].attribute; | ||
|
|
||
| if ( htmlAttribute === 'src' || htmlAttribute === 'href' ) { | ||
|
There was a problem hiding this comment. What alternatives have you considered here? Isn't the list of exceptions based on the currently supported blocks and their attributes? How will it work with different block attributes that translate into HTML attributes? There was a problem hiding this comment. I haven't worked on it since I considered it outside the scope of PR. I've simply moved the current implementation here. I think it's better to continue in a follow-up. |
||
| updateBoundAttibute( null ); | ||
| return; | ||
| } | ||
|
|
||
| updateBoundAttibute( placeholder ); | ||
| } | ||
| }, [ | ||
| updateBoundAttibute, | ||
| propValue, | ||
| attrValue, | ||
| placeholder, | ||
| name, | ||
| attrName, | ||
| ] ); | ||
|
|
||
| return null; | ||
| }; | ||
|
|
||
| /** | ||
| * BlockBindingBridge acts like a component wrapper | ||
| * that connects the bound attributes of a block | ||
| * to the source handlers. | ||
| * For this, it creates a BindingConnector for each bound attribute. | ||
| * | ||
| * @param {Object} props - The component props. | ||
| * @param {Object} props.blockProps - The BlockEdit props object. | ||
| * @param {Object} props.bindings - The block bindings settings. | ||
| * @return {null} This is a data-handling component. Render nothing. | ||
| */ | ||
| function BlockBindingBridge( { blockProps, bindings } ) { | ||
| const blockBindingsSources = unlock( | ||
| useSelect( blocksStore ) | ||
| ).getAllBlockBindingsSources(); | ||
|
|
||
| return ( | ||
| <> | ||
| { Object.entries( bindings ).map( | ||
| ( [ attrName, boundAttribute ] ) => { | ||
| // Bail early if the block doesn't have a valid source handler. | ||
| const source = | ||
| blockBindingsSources[ boundAttribute.source ]; | ||
| if ( ! source?.useSource ) { | ||
| return null; | ||
| } | ||
|
|
||
| return ( | ||
| <BindingConnector | ||
| key={ attrName } | ||
| attrName={ attrName } | ||
| source={ source } | ||
| blockProps={ blockProps } | ||
| args={ boundAttribute.args } | ||
| /> | ||
| ); | ||
| } | ||
| ) } | ||
| </> | ||
| ); | ||
| } | ||
|
|
||
| const withBlockBindingSupport = createHigherOrderComponent( | ||
| ( BlockEdit ) => ( props ) => { | ||
| /* | ||
| * Create binding object filtering | ||
| * only the attributes that can be bound. | ||
| */ | ||
| const bindings = Object.fromEntries( | ||
| Object.entries( props.attributes.metadata?.bindings || {} ).filter( | ||
| ( [ attrName ] ) => canBindAttribute( props.name, attrName ) | ||
| ) | ||
| ); | ||
|
|
||
| return ( | ||
| <> | ||
| { Object.keys( bindings ).length > 0 && ( | ||
| <BlockBindingBridge | ||
| blockProps={ props } | ||
| bindings={ bindings } | ||
| /> | ||
| ) } | ||
| <BlockEdit { ...props } /> | ||
| </> | ||
| ); | ||
| }, | ||
| 'withBlockBindingSupport' | ||
| ); | ||
|
|
||
| /** | ||
| * Filters a registered block's settings to enhance a block's `edit` component | ||
| * to upgrade bound attributes. | ||
| * | ||
| * @param {WPBlockSettings} settings - Registered block settings. | ||
| * @param {string} name - Block name. | ||
| * @return {WPBlockSettings} Filtered block settings. | ||
| */ | ||
| function shimAttributeSource( settings, name ) { | ||
| if ( ! canBindBlock( name ) ) { | ||
| return settings; | ||
| } | ||
|
|
||
| return { | ||
| ...settings, | ||
| edit: withBlockBindingSupport( settings.edit ), | ||
| }; | ||
| } | ||
|
|
||
| addFilter( | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's not a workaround and necessary. Attribute values should be serializable and deserializable.
RichTextDatais the only special type of value AFAIK. However, we can implement some kind of universal contract for values to serialize/deserialize automatically though.For instance, when registering a new custom type, we need to specify both a serialize and a deserialize function.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added this checking as a quick temporary solution. This is needed because when comparing initially the value provided by the external source (HTML) with the bound attribute( RichTextData instance), it will always be different.