{% /html %} ```` ## Examples ### Basic Usage ````liquid theme={null} ```sql daily_orders select 'Mon' as day, 120 as orders union all select 'Tue', 180 union all select 'Wed', 90 ``` {% html %}

{% /html %} ```` ### Responsive D3 chart from a CDN ```liquid theme={null} {% html %}

{% /html %} ``` ## The evidence API Every script inside the block can reach a single `evidence` object. It is the only bridge to the page — data, variables, theme, filters, and lifecycle all hang off it. | Member | What it does | | - | - | | `evidence.query(name)` | Rows for a named query or `sql` block declared on the page. Returns a promise, and always returns the latest interpolated rows. | | `evidence.variables` | Values passed on the tag via `variables=` (see below). Always current. | | `evidence.onVariablesChange(cb)` | Fires when any `variables` value changes. Returns an unsubscribe fn. | | `evidence.theme` | `{ mode, palette }` — the resolved light/dark mode and categorical color palette. | | `evidence.onThemeChange(cb)` | Fires when the theme or mode changes. Returns an unsubscribe fn. | | `evidence.onResize(cb)` | Fires when the block's width changes. Returns an unsubscribe fn (see Sizing). | | `evidence.subscribe(cb)` | Fires on any state change — variables, filters, or theme. Returns an unsubscribe fn. | | `evidence.filters` | `get()`, `set(id, value)`, `create(id, value, { column })`, `subscribe(cb)` — see Parameterizing Queries. | | `evidence.modal.open({ title, html })` / `.close()` | Open a full-page modal the parent renders over the report, in a nested sandbox with the same `evidence` API. | | `evidence.navigate(path)` | Navigate to another page in the app (a drill-through). Same-origin internal paths only. | | `evidence.openUrl(url)` | Open an external `http(s)` URL in a new tab. The host must be named in the block (see Links). | | `evidence.ready()` | Signal that the first render is done. Call it after async draws so PDF/PNG export captures a finished frame. | The reliable pattern is to wrap your draw in `async function render() { … }`, then `evidence.subscribe(render); await render();` — `evidence.query` returns fresh rows each call, so the same function serves the first render and every reactive re-render. ## Links Links inside the block work the way they do in markdown, with one difference: external URLs always open in a new tab, because the block is an isolated frame and navigating it to another site would just blank the block. * **External:** `Open ticket` opens the URL in a new tab. `target="_blank"` is accepted but not required. From a script — a click on a card, a map marker, a chart segment — call `evidence.openUrl(url)` instead. It takes an absolute `http(s)` URL and always opens a new tab; the report page itself is never navigated off-site. * **Internal:** `` is a same-tab drill-through to another page in the app, routed the same way as a markdown link `[x](/my-project/reports/detail)`, so it is correct in published, preview, and editor contexts. From a script, call `evidence.navigate(path)`. Add `target="_blank"` to open the app page in a new tab instead. Browsers only open new tabs from a user gesture, so call `evidence.openUrl` from a click handler, not on load. Modifier clicks (Cmd/Ctrl-click, middle-click) are left to the browser, and a click your own handler has already `preventDefault()`ed is left alone. The same rules apply inside a modal opened with `evidence.modal.open`. ``` {% html %}

{% /html %} ``` ### Which hosts a block can open A block can only open hosts it names. The block runs in a sandbox so that code inside it — including any library it loads from a CDN — cannot send your report data anywhere you didn't choose, and a URL opened in a new tab is one way data could leave. So the page, not the block, opens the tab, and it checks the host first: * Any `https://host` written in the block's source is allowed automatically. The example above needs no configuration: `support.example.com` appears in the `evidence.openUrl` template string. * If the URL comes entirely from data — `evidence.openUrl(row.ticket_url)`, where no host appears in the source — name it on the tag: `{% html linkHosts="support.example.com" %}`. Comma-separate several hosts. The editor warns when it sees an `openUrl` call like this without `linkHosts`. * A click on a host that isn't named does nothing, and the diagnostics feed shows which host was blocked and the exact `linkHosts` line to add. Hosts match exactly (including any port); there are no wildcards. Links to other pages in the app are always allowed. ``` {% html linkHosts="support.example.com" %}

{% /html %} ``` ## Passing Variables The `{% html %}` block runs verbatim in an isolated iframe: the body is never interpolated, so the way a page-level value (frontmatter, a component attribute, a repeat-scoped value, a filter value, a literal) reaches your code is the `variables={…}` attribute. Nothing crosses into the sandbox that you didn't pass. Values are evaluated on the page, snapshotted into the iframe, and read as `evidence.variables`. ``` --- selected_country: France --- {% dropdown name=region values="north,south,east,west" defaultValue="north" /%} {% html variables={ greeting=$selected_country region="{{ region.literal }}" limit=10 } %}

{% /html %} ``` **Inside a repeat:** pass the iteration's value through with `{{ }}`, so each iteration gets a different `evidence.variables`. ``` {% repeat id="category_repeat" data="demo.daily_orders" column="category" %} {% html variables={ category="{{ category_repeat }}" } %}

{% /html %} {% /repeat %} ``` **Notes:** * **`{{ $x }}` does not interpolate inside the block** — the body is verbatim. For plain text, write it in markdown outside the block (where `{{ $x }}` works normally); inside the block, pass the value via `variables=` and read `evidence.variables.x` from a script. Validation catches both mistakes with the exact fix. * **Reading a value you didn't pass returns `undefined`** — only `variables=` entries exist inside the sandbox. Validation flags visible reads with no matching entry. * **Reactivity:** `const speed = evidence.variables.speed` at the top of your script captures the value once — when the attribute or filter behind it changes, your constant does not. `evidence.variables` itself is always current, so either read it where you use it (e.g. inside your render/animation loop), or register `evidence.onVariablesChange((vars) => { /* re-render */ })` for structural changes. A change that arrives while nothing is listening logs a console warning explaining this. * Values must be serializable primitives (string / number / boolean / null). Objects, arrays, and functions are dropped before the snapshot reaches the iframe — flatten them at the call site (`start=$period.start`), or query them through `evidence.query()` instead. * `evidence.variables` is a snapshot; mutating the returned object doesn't change anything (each read returns a fresh shallow copy). * For *row data*, prefer `evidence.query("query_name")` over packing rows into `variables=` — query results stream lazily and aren't limited to primitives. ## Parameterizing Queries from JS `evidence.query()` takes no parameters. To re-run a query with different inputs, create a filter in your JS and reference it from the SQL: the query re-runs server-side, and the predicate is applied on the warehouse, so only matching rows enter the iframe. Prefer this over pulling a whole table and filtering client-side. The loop has four steps: 1. **Declare** the filter in your script: `evidence.filters.create("region", "north")` (create it before anything `.set`s it). 2. **Reference** it from any sql fence with `{{ region }}` (quoted value) or `{{ region.literal }}` (raw, for numbers). 3. **Set** it from your interaction handler: `evidence.filters.set("region", picked)` — the query re-runs on the warehouse. 4. **React**: `evidence.subscribe(render)` fires when the fresh result lands; call `evidence.query()` again inside `render` to get the new rows. ```` ```sql region_sales select category, sum(total_sales) as total from demo.daily_orders where region = {{ region }} group by category order by total desc ``` {% html %}

{% /html %} ```` **When not to use this:** for high-frequency interaction over a dataset that fits in memory (scrubbing an animation slider, hover highlights), fetch once with `evidence.query()` and filter/redraw client-side — a warehouse round-trip per frame is the wrong tool. Use the filter loop when the table is too big to pull, or when other components on the page should react too (`evidence.filters.create(id, value, { column: "the_column" })` makes built-in charts with `filters="id"` follow your selection). ## Sizing and Responsiveness By default the block **autosizes**: it grows and shrinks to fit its content height and fills the page width. Give your content a real height so it has something to size to: * A fixed-pixel element, or a responsive SVG sized with `viewBox` + `width:100%` + `height:auto` (which takes its height from the aspect ratio). * A `height:100%` element has nothing to fill in autosize mode. For a chart that fills a fixed box (canvas, ECharts, and Chart.js all read the container's size), pass `height=` in pixels on the tag — that pins the box and makes the mount area full-height, so `height:100%` works. Width reflows with the page, but a chart only follows if you build for it: scale SVGs with `viewBox` + `width:100%` (no redraw needed), or redraw from `evidence.onResize(cb)` (call the library's resize method in the callback for canvas/ECharts/Chart.js). A hardcoded pixel width won't reflow. The block is an isolated iframe, so its own width is the viewport width — CSS `@media (max-width: 480px)` queries fire at the *block's* width, which makes them behave like container queries. Use them to reflow at narrow widths (stack columns, shrink type). Tooltips and popovers are **clipped at the block edges** — CSS `overflow` can't escape the frame. Position them relative to your own container and clamp into bounds (e.g. `left = Math.max(0, Math.min(x, mount.clientWidth - tip.offsetWidth))`), or flip them near an edge. On pages with card mode enabled, the block renders inside a card. Pass `card=false` to drop the card and render it directly on the page background — useful for banners, headers, or visuals that bring their own framing. ## Network Allowlist Author code inside an `{% html %}` block runs in a sandboxed iframe with a content-security-policy that blocks all network traffic except to the curated hosts below. `fetch`, XHR, `d3.csv`, and `d3.json` work against these hosts; everything else is blocked at the browser level. For data from the user's own report, always use `evidence.query("query_name")` instead — page rows live in the parent context and have no URL to fetch. ### Script CDNs Used for loading JS libraries via `