1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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 callable $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 string[] $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 );
}
|
