Logo
Logo

Global Settings API

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


<?php

use function \Breakdance\Elements\controlSection;
use function \Breakdance\Elements\control;

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']
    );
});

Adding Custom Control Section to Breakdance Global Settings with breakdance_global_settings_control_sections_append

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, simply produce them visually using Element Studio, and then paste in the generate code (the c function returns a control section).

Return a Control[] from this filter.

Outputting CSS Based On The Control Values with breakdance_global_settings_css_twig_template_append

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.

Supporting Certain Responsive Controls With breakdance_global_settings_property_paths_to_whitelist_in_flat_props_append

If a control value needs to be available at breakpoints other than the base breakpoint, the path to that control must be whitelisted.

Return string[] from this filter.