|
1 <?php |
|
2 /** |
|
3 * Block Bindings API |
|
4 * |
|
5 * Contains functions for managing block bindings in WordPress. |
|
6 * |
|
7 * @package WordPress |
|
8 * @subpackage Block Bindings |
|
9 * @since 6.5.0 |
|
10 */ |
|
11 |
|
12 /** |
|
13 * Registers a new block bindings source. |
|
14 * |
|
15 * Registering a source consists of defining a **name** for that source and a callback function specifying |
|
16 * how to get a value from that source and pass it to a block attribute. |
|
17 * |
|
18 * Once a source is registered, any block that supports the Block Bindings API can use a value |
|
19 * from that source by setting its `metadata.bindings` attribute to a value that refers to the source. |
|
20 * |
|
21 * Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook. |
|
22 * |
|
23 * |
|
24 * ## Example |
|
25 * |
|
26 * ### Registering a source |
|
27 * |
|
28 * First, you need to define a function that will be used to get the value from the source. |
|
29 * |
|
30 * function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) { |
|
31 * // Your custom logic to get the value from the source. |
|
32 * // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API. |
|
33 * $value = $source_args['key']; |
|
34 * |
|
35 * return "The value passed to the block is: $value" |
|
36 * } |
|
37 * |
|
38 * The `$source_args` will contain the arguments passed to the source in the block's |
|
39 * `metadata.bindings` attribute. See the example in the "Usage in a block" section below. |
|
40 * |
|
41 * function my_plugin_register_block_bindings_sources() { |
|
42 * register_block_bindings_source( 'my-plugin/my-custom-source', array( |
|
43 * 'label' => __( 'My Custom Source', 'my-plugin' ), |
|
44 * 'get_value_callback' => 'my_plugin_get_custom_source_value', |
|
45 * ) ); |
|
46 * } |
|
47 * add_action( 'init', 'my_plugin_register_block_bindings_sources' ); |
|
48 * |
|
49 * ### Usage in a block |
|
50 * |
|
51 * In a block's `metadata.bindings` attribute, you can specify the source and |
|
52 * its arguments. Such a block will use the source to override the block |
|
53 * attribute's value. For example: |
|
54 * |
|
55 * <!-- wp:paragraph { |
|
56 * "metadata": { |
|
57 * "bindings": { |
|
58 * "content": { |
|
59 * "source": "my-plugin/my-custom-source", |
|
60 * "args": { |
|
61 * "key": "you can pass any custom arguments here" |
|
62 * } |
|
63 * } |
|
64 * } |
|
65 * } |
|
66 * } --> |
|
67 * <p>Fallback text that gets replaced.</p> |
|
68 * <!-- /wp:paragraph --> |
|
69 * |
|
70 * @since 6.5.0 |
|
71 * |
|
72 * @param string $source_name The name of the source. It must be a string containing a namespace prefix, i.e. |
|
73 * `my-plugin/my-custom-source`. It must only contain lowercase alphanumeric |
|
74 * characters, the forward slash `/` and dashes. |
|
75 * @param array $source_properties { |
|
76 * The array of arguments that are used to register a source. |
|
77 * |
|
78 * @type string $label The label of the source. |
|
79 * @type callable $get_value_callback A callback executed when the source is processed during block rendering. |
|
80 * The callback should have the following signature: |
|
81 * |
|
82 * `function( $source_args, $block_instance, $attribute_name ): mixed` |
|
83 * - @param array $source_args Array containing source arguments |
|
84 * used to look up the override value, |
|
85 * i.e. {"key": "foo"}. |
|
86 * - @param WP_Block $block_instance The block instance. |
|
87 * - @param string $attribute_name The name of an attribute. |
|
88 * The callback has a mixed return type; it may return a string to override |
|
89 * the block's original value, null, false to remove an attribute, etc. |
|
90 * @type string[] $uses_context Optional. Array of values to add to block `uses_context` needed by the source. |
|
91 * } |
|
92 * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure. |
|
93 */ |
|
94 function register_block_bindings_source( string $source_name, array $source_properties ) { |
|
95 return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties ); |
|
96 } |
|
97 |
|
98 /** |
|
99 * Unregisters a block bindings source. |
|
100 * |
|
101 * @since 6.5.0 |
|
102 * |
|
103 * @param string $source_name Block bindings source name including namespace. |
|
104 * @return WP_Block_Bindings_Source|false The unregistered block bindings source on success and `false` otherwise. |
|
105 */ |
|
106 function unregister_block_bindings_source( string $source_name ) { |
|
107 return WP_Block_Bindings_Registry::get_instance()->unregister( $source_name ); |
|
108 } |
|
109 |
|
110 /** |
|
111 * Retrieves the list of all registered block bindings sources. |
|
112 * |
|
113 * @since 6.5.0 |
|
114 * |
|
115 * @return WP_Block_Bindings_Source[] The array of registered block bindings sources. |
|
116 */ |
|
117 function get_all_registered_block_bindings_sources() { |
|
118 return WP_Block_Bindings_Registry::get_instance()->get_all_registered(); |
|
119 } |
|
120 |
|
121 /** |
|
122 * Retrieves a registered block bindings source. |
|
123 * |
|
124 * @since 6.5.0 |
|
125 * |
|
126 * @param string $source_name The name of the source. |
|
127 * @return WP_Block_Bindings_Source|null The registered block bindings source, or `null` if it is not registered. |
|
128 */ |
|
129 function get_block_bindings_source( string $source_name ) { |
|
130 return WP_Block_Bindings_Registry::get_instance()->get_registered( $source_name ); |
|
131 } |