mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
feat(core): declarative variable bindings — data-var-src, data-var-text, css custom props
This commit is contained in:
@@ -32,6 +32,8 @@ Hyperframes uses HTML data attributes to control timing, media playback, and [co
|
||||
| `data-composition-src` | `"./intro.html"` | Path to external [composition](/concepts/compositions) HTML file |
|
||||
| `data-variable-values` | `'{"title":"Hello"}'` | JSON object of values passed to a nested composition. Inside the sub-composition, read them via `window.__hyperframes.getVariables()` — the runtime layers these over the sub-comp's own `data-composition-variables` defaults and exposes the merged result on a per-instance basis (the same source can be embedded multiple times with different values). |
|
||||
| `data-composition-variables` | `'[{"id":"title","type":"string","label":"Title","default":"Hello"}]'` | JSON array of declared variables (`id`, `type`, `label`, `default`). Drives Studio editing UI and provides defaults read by `window.__hyperframes.getVariables()`. The CLI flag `hyperframes render --variables '<json>'` overrides these defaults at top-level render time; host elements override them per-instance via `data-variable-values`. |
|
||||
| `data-var-src` | `"heroImage"` | Binds the element's `src` to a declared variable — the runtime substitutes the value (URL string or image `{url}`) in preview and render; the authored `src` stays as the fallback. |
|
||||
| `data-var-text` | `"title"` | Binds the element's own text to a scalar variable. Element children (nested clips, animated spans) are preserved. Scalar variables are also applied as `--{id}` CSS custom properties on the composition root, so `color: var(--accent)` responds to overrides. |
|
||||
|
||||
## Element Visibility
|
||||
|
||||
|
||||
@@ -196,6 +196,51 @@ Inside any composition script, call `window.__hyperframes.getVariables()` to get
|
||||
|
||||
`__hyperframes.getVariables()` is a shorthand for `window.__hyperframes.getVariables()` and works in both top-level and sub-composition scripts. The runtime automatically scopes sub-compositions so each instance sees its own resolved values.
|
||||
|
||||
## Declarative Bindings (No Script Required)
|
||||
|
||||
For the common cases — replaceable media, dynamic text, and CSS-driven styling — you don't need a script at all. The runtime resolves these bindings once at load, identically in preview and render:
|
||||
|
||||
- **`data-var-src="id"`** — sets the element's `src` from the variable value (a URL string, or an image value's `{url}`). The authored `src` stays as the fallback when the variable resolves to nothing:
|
||||
|
||||
```html
|
||||
<img class="clip" data-start="0" data-duration="5"
|
||||
data-var-src="heroImage" src="fallback.jpg" />
|
||||
```
|
||||
|
||||
<Note>
|
||||
`data-var-src` is only honored on media elements (`img`, `video`, `audio`,
|
||||
`source`) and only for safe URL protocols (`http(s):`, `blob:`, relative
|
||||
paths, and `data:image/…`). A binding on a script-executing tag such as
|
||||
`<iframe>`/`<script>`, or a value using `javascript:`/`data:text/html`, is
|
||||
ignored — variable values may be attacker-influenced, so this prevents them
|
||||
from becoming a script-injection sink. Scalar values applied as CSS custom
|
||||
properties are likewise stripped of declaration-smuggling characters
|
||||
(`; { } < >`).
|
||||
</Note>
|
||||
|
||||
- **`data-var-text="id"`** — sets the element's text content from a scalar variable:
|
||||
|
||||
```html
|
||||
<h1 class="clip" data-start="0" data-duration="5" data-var-text="title">Fallback title</h1>
|
||||
```
|
||||
|
||||
- **CSS custom properties** — every scalar variable is applied as `--{id}` on its composition root (font values apply their family name), so plain CSS bindings respond to render/preview overrides:
|
||||
|
||||
```css
|
||||
.card-title { color: var(--accent); font-family: var(--brandFont), sans-serif; }
|
||||
```
|
||||
|
||||
Bindings resolve against the element's owning composition, so sub-composition instances see their own per-instance values. The Studio Variables panel counts these bindings as usage. Use `getVariables()` in a script only when you need logic beyond direct substitution (loops, conditionals, derived values).
|
||||
|
||||
<Note>
|
||||
**Content Security Policy.** The preview server injects override values via an
|
||||
inline `<script>window.__hfVariables=…</script>` tag. If you embed the preview
|
||||
behind a strict CSP (`script-src 'self'` with no `'unsafe-inline'`), that tag is
|
||||
blocked and the preview silently falls back to declared defaults — allow it with
|
||||
a nonce or hash. The declarative-binding runtime itself emits no inline scripts,
|
||||
and the final rendered output is unaffected.
|
||||
</Note>
|
||||
|
||||
## Per-instance Overrides (Sub-compositions)
|
||||
|
||||
When embedding a composition inside another, use `data-variable-values` on the host element to pass a JSON object of override values for that particular instance:
|
||||
|
||||
@@ -58,7 +58,9 @@ Common sizes:
|
||||
| `data-volume` | audio, video | No | Volume level from `0` to `1`. Default: `1`. |
|
||||
| `data-composition-id` | div | On compositions | Unique composition ID. Must match the key used in `window.__timelines`. |
|
||||
| `data-composition-src` | div | No | Path to external composition HTML file (for [nested compositions](#composition-clips)). |
|
||||
| `data-variable-values` | div | No | JSON object of values passed to a nested composition. The framework carries the values through, but your composition script must read and apply them manually. |
|
||||
| `data-variable-values` | div | No | JSON object of values passed to a nested composition. Read via `getVariables()` in scripts, or consumed automatically by declarative bindings. |
|
||||
| `data-var-src` | img, video, audio | No | Binds the element's `src` to a declared variable id — the runtime substitutes the value (URL string or image `{url}`); the authored `src` is the fallback. |
|
||||
| `data-var-text` | any | No | Binds the element's own text to a scalar variable id. Element children are preserved. |
|
||||
| `data-width` | div | On compositions | Composition width in pixels. |
|
||||
| `data-height` | div | On compositions | Composition height in pixels. |
|
||||
|
||||
@@ -152,7 +154,7 @@ Common sizes:
|
||||
- Each nested composition has its own `window.__timelines` entry, registered by its own `<script>` block
|
||||
- The framework automatically nests sub-timelines — do not manually add them to the parent timeline
|
||||
- Any composition can be nested inside any other — there is no special "root" type
|
||||
- Per-instance values can be passed with `data-variable-values`, but the nested composition must read and apply those values itself
|
||||
- Per-instance values can be passed with `data-variable-values`; sub-composition scripts read them via `getVariables()`, and `data-var-*` bindings / `var(--id)` CSS resolve them automatically
|
||||
|
||||
For more on how compositions work, see [Compositions](/concepts/compositions).
|
||||
</Accordion>
|
||||
|
||||
Reference in New Issue
Block a user