Builder Vocabulary

Filters that add to the lists the builder offers — dividers, variables, controls, macros.
Each takes a different shape, so the examples below are the reference.

Design

`oxygen_shape_dividers`

Filter, $dividers. The shape divider list. Each entry is a text label and a value
holding the SVG markup itself.

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

    return $dividers;
});

`oxygen_variables`

Filter, $variables. The site's variables,
before the builder and the front end see them. Every entry needs all seven keys:

add_filter('oxygen_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;
});

collection groups the variable in the panel; a name of your own keeps your entries out of
the user's own groups.

`oxygen_design_library_providers`

Filter, $providers. The sources the Design Library offers. An entry is a name and the
url its manifest is served from.

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

    return $providers;
});

Elements

`oxygen_universal_controls`

Filter, $controls. Controls present on every element. The array has three keys —
contentSections, designSections and settingsSections — each holding
controls built with BreakdanceElementsc().

add_filter('oxygen_universal_controls', function ($controls) {
    $controls['settingsSections'][] = BreakdanceElementsc(
        'my_plugin',
        'My Plugin',
        [
            BreakdanceElementsc('tracking_id', 'Tracking ID', [], ['type' => 'text']),
        ],
        ['type' => 'section']
    );

    return $controls;
});

Everything you add here appears on every element in the builder, so keep it to one section.

`oxygen_element_controls`

Filter, $controls, $element. The controls of one element, in the same three-key shape.
$element is the element's class name, so $element::slug() tells you which one you're
looking at.

add_filter('oxygen_element_controls', function ($controls, $element) {
    if ($element::slug() !== 'OxygenElements\Image') {
        return $controls;
    }

    $controls['settingsSections'][] = BreakdanceElementsc(
        'my_plugin_image',
        'Licensing',
        [
            BreakdanceElementsc('license', 'License', [], ['type' => 'text']),
        ],
        ['type' => 'section']
    );

    return $controls;
}, 10, 2);

`oxygen_element_default_properties`

Filter, $defaultProperties. An element's default property values, as returned by its
defaultProperties(). Note that the element itself is not passed — the filter sees the
array and nothing identifying whose it is, so it can only be used for changes that are safe
across every element.

add_filter('oxygen_element_default_properties', function ($defaults) {
    if (isset($defaults['design']['list']['layout'])) {
        $defaults['design']['list']['layout'] = 'grid';
    }

    return $defaults;
});

`oxygen_register_macros`

Action. Register Twig macros your elements can
call. Pass the macro's source, its slug, and the directory it lives in:

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

`oxygen_reusable_dependencies_urls`

Filter, $urls. Shared script URLs, keyed by name. See the
Dependencies API, which is entirely about this filter.