Property Paths

The Property Paths tab holds three settings that all work the same way: you give Oxygen
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

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, Oxygen 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-4881530-120 { 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 Oxygen won't do that on every
keystroke of every control. This list names the controls worth the round trip.

Oxygen'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.

The two vertical margin bars above are the overwhelmingly common configuration — around 145
of Oxygen's and Breakdance's elements ship exactly that pair, and only a handful add the
horizontal or inside- variants. Add those only where they make sense; handles on all four
edges are more clutter than help.

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.