Property Paths

The Property Paths tab holds path settings that all work the same way: you give Breakdance
a list of paths into your control values, and it changes how those values are treated.

They're the least obvious settings in Element Studio and the ones most likely to explain a
bug you can't otherwise account for — a value that's mysteriously empty on tablet, or a
builder that doesn't update when you type.

A path is the dotted route to a control, exactly as you'd write it in a template:

content.card.heading
design.container.background

Dynamic Property Paths

Legacy explicit dynamic property paths identify controls that accept dynamic values and their accepted types, such as string or image_url. The section appears when the element has explicit dynamic paths. New controls should use their own Enable dynamic property metadata. For existing explicit paths, check the list after copying, moving, or renaming controls; re-enable dynamic support on copied controls as needed. See Controls for configuring and binding those values.

Property paths to whitelist in flat props

The symptom this fixes: a control's value is correct in the desktop CSS and empty in
every media query below it.

Before your CSS template runs, Breakdance flattens the element's properties for the breakpoint
it's rendering. Values from a control with breakpoints enabled get resolved to that
breakpoint's value. Values from a control without breakpoints — a toggle, a dropdown, a
piece of content — are kept only on the base breakpoint pass. On every other pass they're
dropped, because a value that can't vary by breakpoint has nothing to say inside a media
query.

That's usually right. It's wrong when a non-responsive control decides something about
responsive output:

{% if content.layout.reverse_on_mobile %}
  .bde-themeless-template-content-area-256146-124 { flex-direction: column-reverse; }
{% endif %}

content.layout.reverse_on_mobile is a plain toggle, so on the mobile pass it's gone, the
if is false, and the rule never renders. Whitelist the path and it survives into every
breakpoint's flattening:

content.layout.reverse_on_mobile

Paths are matched by prefix, so whitelisting content.layout keeps everything in that
section. Whitelist only what you actually read in the CSS template — the whole point of
dropping the rest is to keep the per-breakpoint property payload small.

Property paths to SSR the element when value changes

The symptom this fixes: the user edits a control and the builder canvas doesn't change
until they reload.

This only applies to elements with an ssr.php.
A Twig-only element re-renders in the browser as the user types, but server-rendered markup
can only be refreshed by asking the server for it again, and Breakdance won't do that on every
keystroke of every control. This list names the controls worth the round trip.

Breakdance's Shortcode element names exactly one:

static function propertyPathsToSsrElementWhenValueChanges()
{
    return ['content.shortcode.full_shortcode'];
}

Change the shortcode, the server re-renders it. Change anything else — a margin, a border —
and it doesn't, because the existing markup is still correct.

The trade-off is direct: each path here is a server request every time that control's value
changes. List the controls whose values appear in the server-rendered output, and nothing
else. Leave the list empty on an element that has an ssr.php and its canvas preview will
look frozen; fill it with every control and the builder will feel slow.

Spacing bars

Spacing bars are the drag handles that appear on an element's edges in the canvas, letting a
user set margin or padding by dragging instead of typing a number. Each entry ties a handle
to a CSS property and to the control whose value it writes:

static function spacingBars()
{
    return [
        ['location' => 'outside-top',    'cssProperty' => 'margin-top',    'affectedPropertyPath' => 'design.spacing.margin_top.%%BREAKPOINT%%'],
        ['location' => 'outside-bottom', 'cssProperty' => 'margin-bottom', 'affectedPropertyPath' => 'design.spacing.margin_bottom.%%BREAKPOINT%%'],
    ];
}

location places the handle: outside-top, outside-bottom, outside-left,
outside-right for margins, and inside-top, inside-bottom, inside-left,
inside-right for padding.

cssProperty is what the drag adjusts visually while it's happening — margin-top,
padding-left, and so on. Pair it with the matching location; an outside- handle driving
a padding- property drags the wrong edge.

affectedPropertyPath is the control the value is written into. Note the
%%BREAKPOINT%% on the end: spacing controls have breakpoints enabled, so the value lives
under a breakpoint key, and the placeholder resolves to whichever breakpoint the user is
editing. Without it the drag would write the desktop value while the user is looking at
mobile.

Add Vertical Spacing Bars

1. On Design, add a section and the spacing margin y preset. This supplies top and bottom margin controls; use layout gap for spacing between siblings where appropriate.
2. In Property Paths > Spacing Bars, add an outside-top handle for margin-top and an outside-bottom handle for margin-bottom.
3. Point each handle at the matching stored control path, including %%BREAKPOINT%% where the responsive value lives. A preset may put the breakpoint in its section path, such as design.spacing.%%BREAKPOINT%%.margin_top, rather than at the end. Use that preset's actual path.
4. Use the preset's code help to add its spacing macro to CSS. The handles update values; the CSS must render them.
5. Save, deselect and reselect the instance, then drag the top and bottom bars. Switch breakpoints to confirm each writes to the intended responsive value.

The shortcut through spacing presets

You rarely write these entries by hand. If your element uses one of the built-in spacing
preset control sections — spacing_all,
spacing_margin_y, spacing_padding_all and the rest — the control itself offers a spacing
bar toggle, and switching it on writes the matching entries into this tab for you, with the
right property paths already filled in. Switching it off removes them again.

Use the preset where you can and this tab becomes read-only. Write the entries by hand only
for a bespoke spacing control that no preset covers.