Skip to main content

Custom Fields

Alongside built-in post fields such as the title, excerpt and featured image, dynamic data can pull from custom fields (post meta) stored on your posts, pages and custom post types. Custom fields appear in the same dynamic data picker as the built-in fields and can be used with any of the data types.

Custom fields are read, not created

Nectarblocks reads custom fields that already exist on your content. It does not create them. Define the field on the post type first, fill it in on your posts, then connect it in the editor.

In particular, adding a custom field while editing a Theme Builder template attaches the value to the template itself, not to the posts the template renders, so it will not appear when editing a post.

There are three ways to provide custom fields, covered below: the Advanced Custom Fields plugin, WordPress custom fields, and meta registered in code.

ACF fields​

When the Advanced Custom Fields (ACF) plugin is active, your field groups are detected automatically. No configuration is needed. Each field group appears as its own group in the dynamic data picker, using the labels you gave the fields.

The following ACF field types are available as dynamic fields:

  • Text: text, textarea, number, email, password, color_picker
  • Rich text: wysiwyg
  • Links: url, page_link, link
  • Choices: select, radio, button_group, checkbox, true_false
  • Date and time: date_picker, date_time_picker, time_picker
  • Relational: taxonomy
  • Media: image, file

Layout fields (accordion, tab, group, clone, flexible_content, repeater) and complex fields (gallery, google_map, oembed, post_object, relationship, user, range, message) are not listed in the picker.

Storing videos in ACF

ACF has no dedicated video field type. To hold a video, use a file field (for uploads to the media library) or a url field (for videos hosted elsewhere). The oembed field type is not supported.

WordPress custom fields​

Plain post meta, added through the block editor's Custom Fields panel or with add_post_meta(), is listed in the picker under a Custom Fields group. The stored value is output as-is, so these work best for plain text and URLs.

Two things to be aware of:

  • The Custom Fields panel is hidden by default in the block editor. Enable it from the editor options menu under Preferences → Panels.
  • The Custom Fields group is built from the meta keys found on the post being previewed. Add the field with a value to at least one post before connecting it in a template.

Registered meta fields​

For custom post types, meta registered in code with register_post_meta() is listed under a Meta Fields group named after the post type (for example Meta Fields: Project), whether or not any post has a value yet:

register_post_meta( 'project', 'video_background', [
	'type'         => 'string',
	'label'        => 'Video Background',
	'single'       => true,
	'show_in_rest' => true,
] );

The label is used as the field's display name in the picker. These groups only appear for custom post types; for the core Post and Page types, use ACF or WordPress custom fields instead.

Custom fields and data types​

Each data type draws on custom fields a little differently:

  • Text: any text-based field can be inserted into a Text block, combined freely with static content.
  • Image: ACF image fields appear alongside the built-in image fields such as the featured image.
  • Video: video sources always come from custom fields. None of the built-in post fields hold a video, so the video picker lists custom fields only.
  • Link: url, page_link and link fields, plus any plain meta field holding a URL.

Example: a per-post video background​

A common use case is a single post template where each post supplies its own background video, the same way each post has its own featured image.

  1. In ACF, create a field group (for example "Post Options") containing a file field named "Video Background", and set its location rule to show on Posts.
  2. Edit a post and upload or select a video in the new field.
  3. In the Theme Builder, open your single post template and select the Row, Column or Flex Box block that should carry the video.
  4. In the block's background settings, open the Video control, click the Dynamic BG Video icon and select the Video Background field.
  5. Save the template.

When a post is viewed, the template pulls the video from that post's field. The same approach works with the Video Player block, and with an ACF image field for the Image background control.