Skip to main content

Scoped scripts

There are two places your SDK code can live. The Quickstart covers the first: one module script on the experience, which imports the SDK, calls connect(), and looks components up by locator. This page covers the second: a scoped script, written on a single element and running with that element already handed to you.

Use a scoped script when the behaviour belongs to one thing — a card that counts its own clicks, a button that toggles its own state. Use an experience-level script when the logic spans components, or has to coordinate them.

Writing one​

Select an element in Flex and open SDK Script in the inspector. Press +, type your code, and use the expand control for a full-size editor.

let clicks = Number(this.getData('clicks') ?? 0)

this.on('component.click', () => {
this.setData('clicks', String(++clicks))
this.setAttribute('opacity', clicks % 2 ? '50' : '100')
})

There is no import and no connect(). this is the Component for the element the script is written on — everything on that page applies, including this.experience for the experience-wide handle, this.on(...) for events, and the capabilities for its type. Locators (findByLocator, findByTag) search the element's own subtree, so on an element with no children they find nothing; reach for this.experience when you need to look further.

await works at the top level of your script.

What to expect at runtime​

  • One script per element, running once, as soon as the experience is ready — the same moment connect() would resolve. On a page navigation, elements mounted fresh run their scripts; elements that survived the navigation don't run again.
  • Published experiences and the preview only. Nothing runs while you're editing on the canvas, so a script can't disturb your design work. Use Preview to try it before publishing.
  • A failure stays on its element. If a script throws, that element's script stops, everything else on the page carries on, and the browser console gets one message naming the element. Your viewers see nothing.

Limits​

Your code is compiled as a module, which sets three rules:

  1. No import declarations. Write const x = await import('https://…') instead — a top-of-file import … from … is a syntax error.
  2. Imports must be absolute URLs. A relative path (./helper.js) has nothing to resolve against. You rarely need an import at all: this is already the SDK.
  3. On your own site, your CSP must allow blob: in script-src. Without it the browser blocks every scoped script on the page. Ceros-hosted pages are fine as they are.

One more, if you embed with Flex SSR: the embed must carry the data-flex-manifest-url attribute, or your scripts have no way to reach the page. The WordPress plugin and AEM connector already emit it; a hand-rolled integration should follow the SSR recipe.