To access the API, see Studio API.
AI
Returns a plain typed namespace exposing AI-relevant information about this Studio instance.
Synchronous surfaces ( schema, catalogue, vocabulary, fragments) are
cheap reads — schema and catalogue re-evaluate current state on every call.
Async surfaces (health) perform data-engine round-trips. |
Returns the built Studio AI tools, bound to this Studio instance and ready for an agent to run.
They read live dashboard state at execute time, so pull the toolkit once and close over it when
declaring an agent's tools (e.g. inside ai: ({ api }) => createAiHarness(api, ...)). |
Build a tool an agent can list, bound to this Studio instance. Pass one of: { name, description, command, result } - a tool whose action is an AgAiCommand. result turns what the command
returned into the response the LLM sees.{ name, description, params, execute } - a tool that runs its own execute, for anything ctx.success / ctx.error.{ kind: 'server', name, description, params } - declared here, executed by the agent's own { kind: 'provided', name, description, provider } - hosted and run by the LLM provider; provider is passed through to the adapter untouched.
The returned tool reads live state when it executes, so build it once and list it from an
agent's tools callback. |
Resolve an AI command bound to this Studio instance. The argument is
either: (builder, lenses) => { input, execute } for a AgAiCommand exposes toJSONSchema(),
parse(), and apply().{ type: 'AgX', params? } to retrieve |
Data
Reload all data from the data sources. |
Returns the data engine this Studio instance is currently using, or undefined if it does
not have one. A Studio configured without the data property never has an engine, and one
that is still loading does not have it yet - the engine is in place by the time the
studioReady event fires.
If Studio created the engine, its lifetime is tied to this Studio instance: the engine is
released when Studio is destroyed. To keep an engine alive across a Studio instance being
destroyed and recreated, or to share one engine between several instances, create it yourself
with createDataEngine() and pass it via the data property. Studio then leaves it in your
hands, and getDataEngine() returns that same engine. |
Lifecycle
Will destroy the Studio instance and release resources.
If you are using a framework you do not need to call this,
as Studio links in with the framework lifecycle.
However if you are using native JavaScript,
you need to call this to avoid a memory leak in your application. |
Returns the studioId for the current Studio instance as specified via the Studio property
studioId or the auto assigned Studio ID if none was provided. |
Localisation
Resolve a locale key to text in the locale now in force, applying localeText and
getLocaleText. How a history entry's labelKey becomes something to show:
api.translate(entry.labelKey, entry.labelVariableValues).
A key Studio does not know is passed to getLocaleText like any other, and falls back to the
key itself where nothing resolves it, so your own keys work alongside Studio's. |
Popups
Open a popup showing a component of your own. The popup is rendered inside Studio, or inside
the element given by the popupParent property, and Studio owns it: the popup closes and
your component is destroyed when Studio is destroyed.
The popup stays open until something closes it: clicking outside it leaves it open, nothing
is dimmed, and the rest of the page stays interactive. The Escape key and the close button in
its title bar close it. To close it from inside your component, supply compParams as a
callback and call the closePopup() function it receives.
closedCallback runs once each time the popup closes, whichever of those closed it.
The popup is sized as it opens and does not grow to fit its content, so set width and
height when your component needs more or less room than the default 600 by 400 pixels.
Several popups can be open at once, each staying open until it is closed. |
Properties
Returns the Studio properties value for a provided key. |
Updates a single Studio property to the new value provided.
(Cannot be used on Initial properties.)
If updating multiple options, it is recommended to instead use api.updateProperties()
which batches update logic. |
Updates the provided subset of Studio properties with the provided values.
(Cannot be used on Initial properties.) |
State
Get the current state of Studio.
Can be used in conjunction with the initialState Studio property
or api.setState() to save and restore Studio state.
The object returned is Studio's own state rather than a copy. Treat it as read-only and
build a new object to pass to api.setState(): mutating this one and handing it back
updates nothing on screen. |
Set the current state of Studio.
Can be used in conjunction with api.getState() or onStateUpdated
to save and restore Studio state.
The state is expected to be a full state object, not a partial state object.
State must be updated immutably as Studio uses reference equality
to determine which parts of state have changed.
options names the change in the undo history and says who made it; see
AgSetStateOptions. |
Undo the last change to the report state (widgets, layout, filters,
schema). View state such as the selected page or selection is
left as it is, then brought back into view for the restored change.
No-op when there is nothing to undo ( getHistory().undo is empty).
Pass a getHistory().undo entry's id to undo every change back through that entry in a
single step; an unknown id is a no-op. |
Redo the change most recently undone. No-op when there is nothing to redo
( getHistory().redo is empty). Making a fresh change discards the redo branch.
Pass a getHistory().redo entry's id to redo every change forward through that entry in a
single step; an unknown id is a no-op. |
The editing history: the live state plus what undo() and redo() would step through, each
entry labelled and timestamped. Drives control enablement (an empty undo stack means there is
nothing to undo) and a history list. History does not survive loading new state. |
Discard the undo and redo history, so getHistory() returns empty stacks and
undo()/redo() become no-ops until the next change. The live state is untouched. |