diff options
Diffstat (limited to '')
| -rw-r--r-- | wp-includes/block-bindings.php | 131 | ||||
| -rw-r--r-- | wp-includes/block-bindings/pattern-overrides.php | 47 | ||||
| -rw-r--r-- | wp-includes/block-bindings/post-meta.php | 70 |
3 files changed, 248 insertions, 0 deletions
diff --git a/wp-includes/block-bindings.php b/wp-includes/block-bindings.php new file mode 100644 index 0000000..cee00e2 --- /dev/null +++ b/wp-includes/block-bindings.php @@ -0,0 +1,131 @@ +<?php +/** + * Block Bindings API + * + * Contains functions for managing block bindings in WordPress. + * + * @package WordPress + * @subpackage Block Bindings + * @since 6.5.0 + */ + +/** + * Registers a new block bindings source. + * + * Registering a source consists of defining a **name** for that source and a callback function specifying + * how to get a value from that source and pass it to a block attribute. + * + * Once a source is registered, any block that supports the Block Bindings API can use a value + * from that source by setting its `metadata.bindings` attribute to a value that refers to the source. + * + * Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook. + * + * + * ## Example + * + * ### Registering a source + * + * First, you need to define a function that will be used to get the value from the source. + * + * function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) { + * // Your custom logic to get the value from the source. + * // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API. + * $value = $source_args['key']; + * + * return "The value passed to the block is: $value" + * } + * + * The `$source_args` will contain the arguments passed to the source in the block's + * `metadata.bindings` attribute. See the example in the "Usage in a block" section below. + * + * function my_plugin_register_block_bindings_sources() { + * register_block_bindings_source( 'my-plugin/my-custom-source', array( + * 'label' => __( 'My Custom Source', 'my-plugin' ), + * 'get_value_callback' => 'my_plugin_get_custom_source_value', + * ) ); + * } + * add_action( 'init', 'my_plugin_register_block_bindings_sources' ); + * + * ### Usage in a block + * + * In a block's `metadata.bindings` attribute, you can specify the source and + * its arguments. Such a block will use the source to override the block + * attribute's value. For example: + * + * <!-- wp:paragraph { + * "metadata": { + * "bindings": { + * "content": { + * "source": "my-plugin/my-custom-source", + * "args": { + * "key": "you can pass any custom arguments here" + * } + * } + * } + * } + * } --> + * <p>Fallback text that gets replaced.</p> + * <!-- /wp:paragraph --> + * + * @since 6.5.0 + * + * @param string $source_name The name of the source. It must be a string containing a namespace prefix, i.e. + * `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric + * characters, the forward slash `/` and dashes. + * @param array $source_properties { + * The array of arguments that are used to register a source. + * + * @type string $label The label of the source. + * @type callback $get_value_callback A callback executed when the source is processed during block rendering. + * The callback should have the following signature: + * + * `function ($source_args, $block_instance,$attribute_name): mixed` + * - @param array $source_args Array containing source arguments + * used to look up the override value, + * i.e. {"key": "foo"}. + * - @param WP_Block $block_instance The block instance. + * - @param string $attribute_name The name of an attribute . + * The callback has a mixed return type; it may return a string to override + * the block's original value, null, false to remove an attribute, etc. + * @type array $uses_context (optional) Array of values to add to block `uses_context` needed by the source. + * } + * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure. + */ +function register_block_bindings_source( string $source_name, array $source_properties ) { + return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties ); +} + +/** + * Unregisters a block bindings source. + * + * @since 6.5.0 + * + * @param string $source_name Block bindings source name including namespace. + * @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise. + */ +function unregister_block_bindings_source( string $source_name ) { + return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name ); +} + +/** + * Retrieves the list of all registered block bindings sources. + * + * @since 6.5.0 + * + * @return WP_Block_Bindings_Source[] The array of registered block bindings sources. + */ +function get_all_registered_block_bindings_sources() { + return WP_Block_Bindings_Registry::get_instance()->get_all_registered(); +} + +/** + * Retrieves a registered block bindings source. + * + * @since 6.5.0 + * + * @param string $source_name The name of the source. + * @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered. + */ +function get_block_bindings_source( string $source_name ) { + return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name ); +} diff --git a/wp-includes/block-bindings/pattern-overrides.php b/wp-includes/block-bindings/pattern-overrides.php new file mode 100644 index 0000000..825152b --- /dev/null +++ b/wp-includes/block-bindings/pattern-overrides.php @@ -0,0 +1,47 @@ +<?php +/** + * Pattern Overrides source for the Block Bindings. + * + * @since 6.5.0 + * @package WordPress + * @subpackage Block Bindings + */ + +/** + * Gets value for the Pattern Overrides source. + * + * @since 6.5.0 + * @access private + * + * @param array $source_args Array containing source arguments used to look up the override value. + * Example: array( "key" => "foo" ). + * @param WP_Block $block_instance The block instance. + * @param string $attribute_name The name of the target attribute. + * @return mixed The value computed for the source. + */ +function _block_bindings_pattern_overrides_get_value( array $source_args, $block_instance, string $attribute_name ) { + if ( empty( $block_instance->attributes['metadata']['name'] ) ) { + return null; + } + $metadata_name = $block_instance->attributes['metadata']['name']; + return _wp_array_get( $block_instance->context, array( 'pattern/overrides', $metadata_name, $attribute_name ), null ); +} + +/** + * Registers Pattern Overrides source in the Block Bindings registry. + * + * @since 6.5.0 + * @access private + */ +function _register_block_bindings_pattern_overrides_source() { + register_block_bindings_source( + 'core/pattern-overrides', + array( + 'label' => _x( 'Pattern Overrides', 'block bindings source' ), + 'get_value_callback' => '_block_bindings_pattern_overrides_get_value', + 'uses_context' => array( 'pattern/overrides' ), + ) + ); +} + +add_action( 'init', '_register_block_bindings_pattern_overrides_source' ); diff --git a/wp-includes/block-bindings/post-meta.php b/wp-includes/block-bindings/post-meta.php new file mode 100644 index 0000000..75062f5 --- /dev/null +++ b/wp-includes/block-bindings/post-meta.php @@ -0,0 +1,70 @@ +<?php +/** + * Post Meta source for the block bindings. + * + * @since 6.5.0 + * @package WordPress + * @subpackage Block Bindings + */ + +/** + * Gets value for Post Meta source. + * + * @since 6.5.0 + * @access private + * + * @param array $source_args Array containing source arguments used to look up the override value. + * Example: array( "key" => "foo" ). + * @param WP_Block $block_instance The block instance. + * @return mixed The value computed for the source. + */ +function _block_bindings_post_meta_get_value( array $source_args, $block_instance ) { + if ( empty( $source_args['key'] ) ) { + return null; + } + + if ( empty( $block_instance->context['postId'] ) ) { + return null; + } + $post_id = $block_instance->context['postId']; + + // If a post isn't public, we need to prevent unauthorized users from accessing the post meta. + $post = get_post( $post_id ); + if ( ( ! is_post_publicly_viewable( $post ) && ! current_user_can( 'read_post', $post_id ) ) || post_password_required( $post ) ) { + return null; + } + + // Check if the meta field is protected. + if ( is_protected_meta( $source_args['key'], 'post' ) ) { + return null; + } + + // Check if the meta field is registered to be shown in REST. + $meta_keys = get_registered_meta_keys( 'post', $block_instance->context['postType'] ); + // Add fields registered for all subtypes. + $meta_keys = array_merge( $meta_keys, get_registered_meta_keys( 'post', '' ) ); + if ( empty( $meta_keys[ $source_args['key'] ]['show_in_rest'] ) ) { + return null; + } + + return get_post_meta( $post_id, $source_args['key'], true ); +} + +/** + * Registers Post Meta source in the block bindings registry. + * + * @since 6.5.0 + * @access private + */ +function _register_block_bindings_post_meta_source() { + register_block_bindings_source( + 'core/post-meta', + array( + 'label' => _x( 'Post Meta', 'block bindings source' ), + 'get_value_callback' => '_block_bindings_post_meta_get_value', + 'uses_context' => array( 'postId', 'postType' ), + ) + ); +} + +add_action( 'init', '_register_block_bindings_post_meta_source' ); |