Make WordPress Core

Changeset 57560


Ignore:
Timestamp:
02/08/2024 08:35:47 AM (4 months ago)
Author:
gziolo
Message:

Editor: Improve code documentation for block bindings

Follow-up [57514].
See #60282.
Props czapla, gziolo, retrofox.

Location:
trunk/src/wp-includes
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/block-bindings.php

    r57526 r57560  
    1313 * Registers a new block bindings source.
    1414 *
    15  * Sources are used to override block's original attributes with a value
    16  * coming from the source. Once a source is registered, it can be used by a
    17  * block by setting its `metadata.bindings` attribute to a value that refers
    18  * to the source.
     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 -->
    1969 *
    2070 * @since 6.5.0
  • trunk/src/wp-includes/class-wp-block-bindings-registry.php

    r57526 r57560  
    3636     * Registers a new block bindings source.
    3737     *
     38     * This is a low-level method. For most use cases, it is recommended to use
     39     * the `register_block_bindings_source()` function instead.
     40     *
     41     * @see register_block_bindings_source()
     42     *
    3843     * Sources are used to override block's original attributes with a value
    3944     * coming from the source. Once a source is registered, it can be used by a
Note: See TracChangeset for help on using the changeset viewer.