Global Settings API

Since Breakdance 1.7, hooks are available to add your own controls to the Breakdance Global Settings panel.

<?php

use function BreakdanceElementscontrolSection;
use function BreakdanceElementscontrol;

add_filter('breakdance_global_settings_control_sections_append', function ($appendedControlSections) {

    $myControlSection = controlSection('my_section', 'My Section', [
        control(
            'my_control',
            'My Control',
            [
                'type' => 'color',
                'layout' => 'inline',
                'colorOptions' => ['type' => 'solidAndGradient']
            ]
        ),
        control(
            'orange_at',
            'Orange At',
            [
                'type' => 'breakpoint_dropdown',
                'layout' => 'inline',
            ]
        )
    ]);

    return array_merge($appendedControlSections, [$myControlSection]);
});

add_filter('breakdance_global_settings_css_twig_template_append', function ($appendedTwigTemplate) {

    $myGlobalSettingsCssTwig = "
        body {
            background-color: {{ settings.my_section.my_control }} !important;
        }
        {% if breakpoint == settings.my_section.orange_at %}
        body {
            background-color: orange !important;
        }
        {% endif %}
        ";

    return $appendedTwigTemplate . $myGlobalSettingsCssTwig;
});

add_filter('breakdance_global_settings_property_paths_to_whitelist_in_flat_props_append', function ($appendedWhitelistedProps) {
    return array_merge(
        $appendedWhitelistedProps,
        ['settings.my_section.orange_at']
    );
});

Add a Control Section

To add a new control section to the Breakdance builder, use the add_filter function with the breakdance_global_settings_control_sections_append hook. This allows for appending new control sections to the existing control sections.

In the filter, create new control sections with the desired controls. For an exhaustive list of control types and their options, create them visually using Element Studio, and then paste in the generated code (the c function returns a control section).

Return a Control[] from this filter.

Generate CSS from Global Settings

To output CSS based on the control values, append a string containing CSS rules to the existing global settings Twig template. In this Twig template, you can output CSS dynamically based on the value of the controls.

Return string from this filter.

Keep Values Available at Other Breakpoints

If a nonresponsive control value needs to be read during CSS passes for other breakpoints, whitelist its property path. In this example, orange_at selects the breakpoint where the orange rule is output, so its value must remain available on those passes. Whitelisting does not make the control itself responsive.

Return string[] from this filter.

Use the Controls

Add this code to your custom plugin, reload the builder, and open Global Settings > My Section. Set My Control and choose Orange At, then save. The example sets the body background globally and overrides it at the chosen breakpoint.

Preserve the incoming values in all three filters so extensions can append sections, CSS, and paths without removing each other's additions.