Skip to main content
Documentation/Developers/APIs/Dynamic Data API

Dynamic Data API

Dynamic data is how an element shows a value
that comes from the site rather than from the person building the page — a post title, a
custom field, a featured image. Breakdance ships fields for WordPress core, ACF, Meta Box and
Toolset. The Dynamic Data API is how a plugin adds its own, so its data appears in the same
picker as everything else.

A field is a PHP class plus a registration call. After registering it, open the Dynamic Data picker on a compatible control to select your field alongside the built-in fields.

Create a Field Class

Save this class in member-level.php in your plugin. The registration code below loads it after Breakdance is available.

PHP
use BreakdanceDynamicDataStringField;
use BreakdanceDynamicDataStringData;

class MyPluginMemberLevel extends StringField
{
    public function label()
    {
        return 'Membership Level';
    }

    public function category()
    {
        return 'My Plugin';
    }

    public function slug()
    {
        return 'myplugin_member_level';
    }

    public function handler($attributes): StringData
    {
        return StringData::fromString((string) get_user_meta(get_current_user_id(), 'member_level', true));
    }
}
PHP
add_action('init', function () {
    if (!function_exists('BreakdanceDynamicDataregisterField')
        || !class_exists('BreakdanceDynamicDataStringField')) {
        return;
    }

    require_once __DIR__ . '/member-level.php';
    BreakdanceDynamicDataregisterField(new MyPluginMemberLevel());
});

Load the subclass inside this guarded setup, after Breakdance is available. A guard around registration cannot protect a subclass loaded earlier without its parent class.

Four methods are required on every field:

Method Returns
label() The field's name in the picker
category() The group it appears under
slug() A unique identifier. Prefix it — the namespace is shared site-wide
handler($attributes) The value, wrapped in the data object your base class expects

Choosing a base class

The base class decides what kind of data the field produces, which in turn decides which
element controls will offer it.

StringField

For text. handler() returns StringData.

PHP
public function handler($attributes): StringData
{
    return StringData::fromString('some string value');
}

StringData::fromString($string) and StringData::emptyString() build one.

String fields get three extra controls for free — Prepend, Append and Limit Characters — plus
a Fallback field, so users can shape the output without you doing anything.

ImageField

For a single image. handler() returns ImageData, and the reliable way to build one is
from a WordPress attachment:

PHP
public function handler($attributes): ImageData
{
    return ImageData::fromAttachmentId($attachmentId);
}

fromAttachmentId() fills in everything the Image element needs. If your image isn't a
WordPress attachment you can populate the object by hand, but url and sizes are
mandatory — sizes being an array keyed by size slug, each value holding file, width,
height and mime-type. Get that wrong and the Image element renders nothing.

GalleryField

For several images. handler() returns GalleryData, whose images property is an array of
ImageData:

PHP
public function handler($attributes): GalleryData
{
    $attachedImages = get_attached_media('image', get_the_ID());

    $gallery = new GalleryData();
    $gallery->images = array_map(
        fn($attachment) => ImageData::fromAttachmentId($attachment->ID),
        $attachedImages
    );

    return $gallery;
}

OembedField

For video, either an oEmbed URL or a direct file. handler() returns OembedData, which
needs embedUrl and type ('oembed' or 'video'), plus provider for oEmbed sources.

PHP
public function handler($attributes): OembedData
{
    return OembedData::fromOembedUrl('https://www.youtube.com/watch?v=…');
}

OembedData::fromOembedUrl($url) fetches the oEmbed data over HTTP — fine for YouTube and
Vimeo, but it is a network request, so don't call it in a loop. OembedData::emptyOembed()
returns an empty object.

RepeaterField

For repeating data, consumed by the
Repeater Fields. handler() returns
RepeaterData (built with RepeaterData::fromArray($rows)), and three more methods are
required: hasSubFields($postId = null), setSubFieldIndex($index) and parentField(). Its category
defaults to "Repeaters". Import each data class used by the handler, or use its fully qualified BreakdanceDynamicData name.

This is the base class the ACF and Meta Box integrations use for repeater fields — read one
of those before writing your own.

Return types

Every field declares which controls may use it, through returnTypes(). Each base class sets
a sensible default — StringField returns ['string'], ImageField returns
['image_url'] — and you override it when a field is legitimately more than one thing:

PHP
public function returnTypes()
{
    return ['string', 'url'];
}

The types in use are:

Type Consumed by
string Any text control
url Link and URL controls
image_url Image controls
gallery Gallery and slideshow controls
video Video controls
query Query controls
repeater The Repeater Field element
google_map Map elements

A field that returns a profile URL should declare ['string', 'url'] — that way it works
both as link destination and as visible text. A field with the wrong return type isn't
broken so much as invisible: it simply never appears in the picker for the control you
wanted it in.

Optional methods

subcategory() — a second level of grouping inside your category, which is what keeps a
plugin with fifty fields navigable.

controls() — extra controls shown when a user picks your field, for parameters your
handler needs. Whatever the user sets arrives in handler()'s $attributes array.

defaultAttributes() — defaults for those controls.

fallbackControl() — the control offered for a fallback value. The string, image and
video base classes already provide one.

availableForPostType($postType) — return false to hide the field on post types it
doesn't apply to.

availableFor() — which builders the field appears in. Defaults to
['breakdance', 'oxygen']; return ['breakdance'] for a Breakdance-only field.

proOnly() — controls the field's built-in availability flag; return false when your field should not use that flag.

Multiple Fields from One Class

A plugin exposing several fields can register configured instances of one class. Save this class in my-plugin-field.php:

PHP
class MyPluginField extends BreakdanceDynamicDataStringField
{
    protected array $fieldData;
    public function __construct(array $fieldData) { $this->fieldData = $fieldData; }
    public function label() { return $this->fieldData['label']; }
    public function category() { return 'My Plugin'; }
    public function subcategory() { return $this->fieldData['group']; }
    public function slug() { return 'myplugin_field_' . $this->fieldData['slug']; }
    public function handler($attributes): BreakdanceDynamicDataStringData
    {
        $value = get_post_meta(get_the_ID(), $this->fieldData['meta_key'], true);
        return BreakdanceDynamicDataStringData::fromString((string) $value);
    }
}

Load and register the instances from your plugin:

PHP
add_action('init', function () {
    if (!function_exists('BreakdanceDynamicDataregisterField')
        || !class_exists('BreakdanceDynamicDataStringField')) {
        return;
    }
    require_once __DIR__ . '/my-plugin-field.php';
    $fields = [
        ['label' => 'Office', 'slug' => 'office', 'group' => 'Company', 'meta_key' => 'office'],
        ['label' => 'Department', 'slug' => 'department', 'group' => 'Company', 'meta_key' => 'department'],
    ];
    foreach ($fields as $field) {
        BreakdanceDynamicDataregisterField(new MyPluginField($field));
    }
});

Each instance needs its own unique slug even though the handler is shared.

The other side of the connection

A field only reaches a user if the element control they're editing accepts its return type.
If you also build elements, switch on Enable dynamic property for the relevant controls
and set what each accepts — that's covered under
Element Studio → Controls.

A working example

Soflyy publishes a sample plugin that registers a string field and an image field:
github.com/soflyy/breakdance-sample-dynamic-data.
Read its field classes and guarded registration as examples; its image example uses an external image service.

Construct Image and Video Data Manually

The attachment helper is preferred for images. If constructing ImageData manually from a valid WordPress attachment, populate the same properties:

PHP
$attachment = wp_prepare_attachment_for_js($attachmentId);
$image = new BreakdanceDynamicDataImageData();
$image->id = (int) $attachment['id'];
$image->alt = $attachment['alt'];
$image->caption = $attachment['caption'];
$image->url = $attachment['url'];
$image->type = $attachment['type'];
$image->sizes = $attachment['sizes'];

Check that the attachment exists before reading its properties. The required properties are url and sizes. The current ImageData properties are id, url, sizes, alt, caption, type, and attributes; the attachment record's filename and mime metadata are not output through this object.

For a direct video file:

PHP
$video = new BreakdanceDynamicDataOembedData();
$video->title = 'Introduction';
$video->provider = 'video';
$video->embedUrl = wp_get_attachment_url($videoAttachmentId);
$video->thumbnail = $thumbnailUrl;
$video->format = 'video/mp4';
$video->type = 'video';

For an oEmbed provider, use OembedData::fromOembedUrl($url). These are handler-body examples: supply your attachment IDs and thumbnail URL, and return the matching data object.

See the canonical Dynamic Data API reference for the original field examples.