Connecting Custom Meta Fields with Block Bindings API

In a previous article, we covered how to build and add fields for metadata natively in the WordPress block editor. In the example, we went through how to build a native UI for meta fields. Our content type was ‘Offices’, for which we added three fields for different types of metadata:

Email
Phone number
Website URL

But how do we show custom fields data in the website when we are using a block theme? We could build a custom block for showing metadata, but that sounds like a lot work for a simple task like this.

Custom fields (meta fields) are used to store additional information for posts, pages, or other types of content in WordPress.

WordPress Block Bindings API

Enter Block Bindings API which allows blocks to read data from custom fields. Or any other data defined in PHP!

Note that at the moment (WordPress version 6.8) only the following Core blocks support Block Bindings API:

Image block
- supports url, alt and title attributes
Paragraph block
- supports content attribute
Heading block
- supports content attribute
Button block
- supports url, text, linkTarget and rel attributes

Let’s Use Paragraph Block to Bind Custom Fields Data

Let’s demonstrate how we can populate custom field data dynamically to the Paragraph block. We can for example create single-office.html template where we create block bindings as seen in next steps.

Basic markup for the paragraph looks like this:

<!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph -->

Next, let’s add custom binding to the paragraph markup where we want to connect the office email:

<!-- wp:paragraph {
  "metadata":{
    "bindings":{
      "content":{
        "source":"mt-features/office-email",
        "args":{
          "key":"office_email"
        }
      }
    }
  }
} -->
<p></p>
<!-- /wp:paragraph -->

In the markup note the source definition: "source":"mt-features/office-email".

We’ll use this unique ID in the next step.

Register Custom Source Using the register_block_bindings_source Function

In the example, our paragraph uses mt-features/office-email as its source. In PHP we can register custom source for this using the register_block_bindings_source function.

add_action( 'init', 'prefix_register_block_bindings' );

function prefix_register_block_bindings() {
  register_block_bindings_source(
    'mt-features/office-email',
    array(
      'label' => __( 'Office email', 'textdomain' ),
      'get_value_callback' => 'prefix_bindings_callback',
    )
  );
}

Note the matching source name: mt-features/office-email.

After this, we can create any PHP logic in callback function prefix_bindings_callback.

PHP Logic in Callback Function

Let’s create callback function to return our office email:

function prefix_bindings_callback( $source_args ) {
  // Get the data from the post meta.
  $office_email = get_post_meta( get_the_ID(), 'office_email', true ) ?? false;

  // Link to the email address.
  if ( $office_email ) {
    $office_email = sprintf(
      '<a href="mailto:%s">%s</a>',
      esc_html( $office_email ),
      esc_html( $office_email )
    );
  }

  // Return the data.
  return $office_email;
}

Note! If office email is not added, there will still be an empty paragraph (<p></p>) in the markup. This is a downside of the Block Bindings API, but in some cases good default values are enough, like mentioned in this 10up article.

See full code example in Github.

Connecting Custom Meta Fields with Block Bindings API

WordPress Block Bindings API

Let’s Use Paragraph Block to Bind Custom Fields Data

Register Custom Source Using the register_block_bindings_source Function

PHP Logic in Callback Function

Further Reading