Dependencies

The Dependencies tab declares the scripts and stylesheets your element needs. Oxygen
loads them only on pages where the element is actually used, so an element that wraps a
charting library costs nothing on the pages that don't have a chart.

Each entry — added with Add Item — is a group with a title and some combination of
files, inline code and conditions.

What an entry can hold

Splitting a single element's needs across several entries is normal and useful, because
conditions are per-entry. Oxygen's own Scroll Progress element uses four: the library, the
plugin it depends on, its own script, and the per-instance initialiser.

URLs and placeholders

Dependency URLs go through the same %%NAME%% substitution as the rest of the element, so
you don't hardcode site paths:

'scripts' => ['%%BREAKDANCE_ELEMENTS_PLUGIN_URL%%dependencies-files/popups@1/popups.js'],
'styles'  => ['%%BREAKDANCE_ELEMENTS_PLUGIN_URL%%dependencies-files/popups@1/popups.css'],

For files in your own plugin, point at your own plugin URL. Shared libraries have a better
option — see reusable dependencies below.

Inline scripts run per instance

inlineScripts entries are Twig templates, and they're where an element initialises itself
with its own settings:

new BreakdanceScrollProgress('.bde-themeless-template-content-area-4881530-120', {
  type: {{ content.tracker.type|json_encode }},
  track: {{ content.tracker.track_progress_of|json_encode }},
  direction: {{ design.tracker.direction|json_encode }}
});

Two things to copy from that:

.bde-themeless-template-content-area-4881530-120 scopes the initialiser to this one instance. Ten copies of the element on
a page produce ten initialisers, each bound to its own node.

|json_encode on every interpolated value. A control value goes straight into a
JavaScript literal, and a user who types an apostrophe would otherwise break the page.
json_encode produces a correctly quoted and escaped JavaScript value, and it handles
numbers, booleans, arrays and objects too. Use it every time — no exceptions.

Conditions

builderCondition and frontendCondition decide whether an entry loads at all. Both take a
snippet of PHP, and both are evaluated with the element's property values interpolated
through Twig first:

'frontendCondition' => '$hasEntranceAnimation = !!'{{design.popup.animation.entrance.animation_type}}'; return $hasEntranceAnimation;',

Only load the animation library when the user actually chose an animation.

The two conditions exist separately because the builder and the front end want different
things. A script that hijacks scrolling, animates on load, or replaces your markup is
usually unwanted inside the builder, where the user needs to keep editing:

'builderCondition' => 'return false;',

That's the most common condition of the two, and it's how Scroll Progress keeps its
initialiser out of the canvas while its library still loads there.

Conditions also accept an object form, ['propertyPath' => 'content.x.y'], which loads the
entry when that property has a value — the same test, expressed without PHP.

Reusable dependencies

Loading GSAP from your own plugin when Oxygen already loads GSAP means the page carries it
twice. Reusable dependencies solve that: a set of named URLs that any element can reference,
resolved to a single copy at render time.

Reference one with a %%BREAKDANCE_REUSABLE_<NAME>%% placeholder in place of a URL:

'scripts' => ['%%BREAKDANCE_REUSABLE_GSAP%%'],

Two are registered out of the box, and Oxygen's animation features use both:

• %%BREAKDANCE_REUSABLE_GSAP%%
• %%BREAKDANCE_REUSABLE_SCROLL_TRIGGER%%

You can register your own, or point the built-in ones at a different version — that's the
Dependencies API, a single filter in PHP.

Keeping page weight down

The whole system is built around loading as little as possible, and it's easy to give that
back:

• Reference reusable dependencies instead of bundling your own copy of a shared library.
• Condition anything optional. An element with five features shouldn't load five
  libraries when the user enabled one.
• Turn scripts off in the builder unless the element genuinely needs them to preview
  correctly.
• Prefer inlineScripts over a per-instance file. A short initialiser inline beats an
  HTTP request.