Overview

Element Studio is a builder for builder elements. It lives inside the Oxygen builder, and
it turns a set of visual panels — controls, HTML, CSS, settings — into a real PHP element
class on disk, one that appears in the Add panel next to Oxygen's own elements and behaves
exactly like them.

If you have ever wanted a Testimonial element with the fields your client actually needs,
or wanted to wrap a JavaScript library in something a non-developer can drop onto a page,
this is the tool for it.

Element Studio is for developers and is provided as-is. That sentence is printed at
the top of the panel, and it's meant literally: no support is provided for elements you
build, and the studio writes PHP files into a plugin folder on your server. Keep those
files in version control.

Opening it

Element Studio is in the builder's Settings menu — the three-dot icon

in the top-right group of the toolbar, immediately right of the undo and redo arrows and
left of the Selectors icon:

Open any page in the Oxygen builder.
Click the Settings icon in the top bar.
Choose Element Studio.

The keyboard shortcut is Cmd+Alt+E (Ctrl+Alt+E
on Windows). It's a toggle: the same menu item closes the studio again.

Element Studio open in the builder, showing the Open and New entries for elements, macros and presets

The studio replaces the properties panel on the right-hand side while it's open. The
canvas stays live, which is the point — an element you're building renders in the page
next to it.

What you can build

The panel opens on six entries, in three pairs:

	What it makes
Open element · New element	A full element: controls, markup, styles, its own Add-panel tile
Open macro · New macro	A reusable Twig macro that elements can call from their HTML
Open preset · New preset	A reusable control section that other elements can pull in whole

Most work starts with New element. Macros and presets are what
you reach for once you have several elements repeating the same markup or the same block
of controls.

Creating an element

New element asks for two things: a name, and a saving location.

The Create new element dialog, asking for a name and a saving location

The name is what appears on the Add-panel tile. The saving location is the plugin folder
the files get written into, and on a stock install your choices are Breakdance Elements
and Oxygen Elements — the two first-party plugins.

Neither of those is where your elements belong. Both are overwritten when Oxygen
updates, taking your work with them. Before you build anything you intend to keep, set up
a plugin of your own to save into — that's what Initial Setup covers, and
it takes about five minutes.

Clicking Create writes the element immediately. This surprises people: the four files
land on disk and the element joins the registry before you have touched the Save
button. Save persists the edits you make afterwards.

An element called "Docs Demo Card" saved to Oxygen Elements produces:

wp-content/plugins/oxygen-elements/elements/Docs_Demo_Card/
├── element.php     the element class — controls, settings, everything below
├── html.twig       the markup (the HTML tab)
├── css.twig        the styles (the CSS tab)
└── default.css     styles that apply before any control is touched (the Default CSS tab)

Note the two spellings of the same name: the folder is Docs_Demo_Card, the class and
slug are OxygenElementsDocsDemoCard. The slug is what everything else — nesting rules,
dynamic data, the MCP tools — refers to.

The tabs

Once an element is open, the studio is ten tabs. Each one writes a specific part of
element.php, and each has its own page here:

Tab	What it controls	Page
Content	The controls on the element's Content tab in the builder	Controls
Design	The controls on its Design tab	Controls
HTML	The Twig template that renders it	HTML
CSS	The Twig-driven stylesheet, keyed to `.bde-themeless-template-content-area-4881530-120`	CSS
Default CSS	Plain CSS applied to every instance	CSS
HTML Attributes	Extra attributes and classes on the wrapper	HTML Attributes
Property Paths	Re-render triggers, flat props, spacing bars	Property Paths
Dependencies	Scripts and styles the element loads	Dependencies
Actions	JavaScript that runs on builder lifecycle events	Actions
Settings	Slug, category, icon, nesting rules, everything else	Element Settings

The header above the tabs holds the element's name, Save, and Delete. Delete asks
for confirmation and then removes the files — there is no undo, which is the other reason
to keep your elements in git.

Reading the built-in elements

Oxygen's own elements are built with exactly this system, and they are the best reference
material available. Every one of them registers itself for editing:

BreakdanceElementStudioregisterElementForEditing(
    "OxygenElements\Shortcode",
    BreakdanceUtilgetdirectoryPathRelativeToPluginFolder(__DIR__)
);

That call is what puts an element in the studio's Open element list. Open one and you
can see how a shipping element sets up its controls, what its Twig looks like, and how its
settings are configured. You can also read the files directly — the Oxygen elements live
in wp-content/plugins/oxygen-elements/elements/.

Editing a first-party element is a fine way to learn and a bad way to work: the next
update overwrites it. Copy what you need into your own plugin instead.