Documentation/Developers/APIs/Hooks Reference/Builder Vocabulary

Builder Vocabulary

Preserve stable slugs and return structures when filtering registries.

Controls

breakdance_element_controls($controls, $element) receives arrays with contentSections, designSections, and settingsSections:

PHP

add_filter('breakdance_element_controls', function ($controls, $element) {
    if ($element::slug() !== 'AcmeElements\NoticeCard') {
        return $controls;
    }
    $controls['settingsSections'][] = BreakdanceElementsc(
        'acme_metadata', 'Acme Metadata',
        [BreakdanceElementsc(
            'reference', 'Reference', [], ['type' => 'text'], false, false
        )],
        ['type' => 'section'], false, false
    );
    return $controls;
}, 10, 2);

The example adds settings.acme_metadata.reference; implement rendering separately. breakdance_universal_controls($controls) uses the same shape for all elements, without an element argument. c() requires breakpoint/hover arguments even when false.

Resources

Hook	Contract
`breakdance_element_default_properties`	Receives and returns default properties. The element identity is not passed.
`breakdance_shape_dividers`	Receives and returns divider records with `text` and SVG `value`. Use trusted SVG markup.
`breakdance_variables`	Receives and returns the variables list. Preserve existing IDs and record structure.
`breakdance_design_library_providers`	Receives and returns provider records, including name and URL.

Variable records contain id, cssVariableName, label, value, type, dynamicData, and collection; runtime filtering does not save editable records. Library provider URLs must be compatible sources; registration supplies no credentials.

Shared Code

breakdance_register_macros() has no arguments. The singleton BreakdanceElementsMacrosController::register($macro, $slug, $directoryPath) registers Twig source/metadata. See macros.

breakdance_reusable_dependencies_urls($urls) filters named asset URLs.

Add a Shape Divider

PHP

add_filter('breakdance_shape_dividers', function ($dividers) {
    $dividers[] = [
        'text' => 'My Divider',
        'value' => file_get_contents(__DIR__ . '/my-divider.svg'),
    ];
    return $dividers;
});

Place my-divider.svg in your plugin next to this file. The text is the picker label; value contains the SVG markup. See the official shape divider example.

Add a Variable

PHP

add_filter('breakdance_variables', function ($variables) {
    $variables[] = [
        'id' => 'my-plugin-brand-red',
        'cssVariableName' => '--brand-red',
        'label' => 'Brand Red',
        'value' => '#C81E1E',
        'type' => 'color',
        'dynamicData' => null,
        'collection' => 'My Plugin',
    ];
    return $variables;
});

Add a Design Library Provider

PHP

add_filter('breakdance_design_library_providers', function ($providers) {
    $providers[] = [
        'name' => 'Our Agency Library',
        'url' => 'https://library.example.com/',
    ];
    return $providers;
});

Replace the example URL with a compatible design library provider.

Register a Twig Macro

PHP

add_action('breakdance_register_macros', function () {
    BreakdanceElementsMacrosController::getInstance()->register(
        file_get_contents(__DIR__ . '/macros/my-macros.twig'),
        'my_plugin_macros',
        BreakdanceUtilgetDirectoryPathRelativeToPluginFolder(__DIR__) . '/macros'
    );
});

← PreviousForms

On this page

Controls Resources Shared Code Add a Shape Divider Add a Variable Add a Design Library Provider Register a Twig Macro

Video tutorials ↗ Facebook group ↗ Support ↗