Custom visual Studio, assets and diagnostics

This page covers the working surfaces around a custom visual's code: the Studio where you edit and save it, the report assets it can reference, the AI panel beside its code, and the diagnostics you read when it fails. The two Studios share a name: the one on this page edits a visual in the visual library and saves it with Save as new version; for a report tile's Studio, where Apply puts code on the tile and versions follow the report's saves, see The custom visual Studio. For what a custom visual is and how it is shared, see Custom visuals and the visual library.

Open the Studio for a library visual

1. Open the visual library (DataPrism > Visuals) and select the visual you want to change.
2. Select Edit code. The button needs the Author DataPrism Custom Visuals permission. See Who can do what in DataPrism.
3. The Studio opens over the library. While the version loads, the editor area reads Loading version....

Edit the files and save a new version

• The Studio holds a file list, an editor and a live preview. The layout control switches between Code (Code only), Split (Code and preview side by side) and Preview (Preview only).
• The files are visual.html, visual.css, visual.js, options.json and sample.json. A template visual shows four of them: it has no visual.js.
• Switching between files keeps your place: the editor keeps its cursor and undo history.
• A draft is valid only when both options.json and sample.json parse.
• Save as new version writes a new version of the library visual. It stays disabled while the draft is invalid or has no changes. With nothing changed, its tooltip reads No changes to save; while saving, the button reads Saving....
• Saving never publishes. The published version moves only through Publish, on the library page. See Custom visuals and the visual library.
• Check lines sit under the file list: blocking problems in red, and up to eight warnings under them.

Upload and reference report assets

1. In edit mode, open the tile's Studio (Edit code), and select assets/ in the file tree. The number beside assets/ counts the report's files; the Visual assets dialog opens.
2. Drop files onto the dialog, or click to pick them. The upload area reads Drop files here, or click to pick them and switches to Uploading.... Files upload one at a time, and one failed file reports Asset not uploaded without stopping the rest.
3. Reference an asset in the code as asset://file-name in markup or CSS, or by file name in a uni.assets call: uni.assets.url(name) gives its blob URL, and uni.assets.bytes(name) gives its bytes.

• With no files yet the dialog reads No assets yet and explains that files are stored with the report and attached by reference. While the list loads it reads Loading visual assets.
• The totals line counts the files and their size, in the form {n} asset(s), {size} in total.
• Two budgets matter. A file above 2 MB gets a large badge, whose tooltip reads Above 2 MB: every frame that references this asset downloads its own copy. At upload, a Large asset warning adds that a visual may transfer at most 8.0 MB of assets.
• The dialog warns when the files of the report would pass that budget: A visual referencing all of them would exceed the 8.0 MB transfer budget.
• Each card offers Copy reference to {fileName}, Download {fileName} and Delete {fileName}. Where the dialog is picking a file for the code you are editing, Use this asset attaches it and closes the dialog.
• Copying a reference confirms with Reference copied; when the clipboard is not available, Reference not copied says so.
• Deleting asks Delete this asset? and notes that the file is removed from the report, and that visuals referencing it will show it as missing.
• A card that cannot render reads Could not load; a file that is gone reads File missing. Non-image files carry a binary badge.
• An SVG that carries <style> or <foreignObject> is sanitised on upload; the SVG sanitised message says the stored file may render differently from the original.

Use the AI panel

• The Studio for a tile can show an AI panel, labelled Custom Visual AI. It works on that tile: it reads the tile's fields and result rows, and its changes arrive in the editor.
• It opens by default when you may use it. Each tile keeps one conversation: a second attempt opens the existing thread.
• If the panel cannot open, it reads The AI for this visual could not be opened.

What a custom visual tile shows

• The visual runs in a sandboxed frame inside its tile. A tile shows it live, paused, stopped or replaced by a placeholder. When a preview image cannot be captured for a card, the card reads Preview unavailable.
• A paused tile reads Paused to keep the page responsive, over a faded snapshot of its last rendered state. Select Activate to run it again.
• When a run fails, a strip appears along the bottom of the tile. Toggle diagnostics opens the drawer; Open studio jumps into the code and appears only for people who can edit the report.
• In edit mode the tile is dragged by its background: the pointer shows a move cursor until you interact with it, and a drag that starts on a control inside the tile never moves the tile.
• A placeholder can also mean the visual was switched off. For what that means and how it is turned back on, see Custom visuals and the visual library.

Read the diagnostics drawer

• Open the drawer from Toggle diagnostics on a failing tile's strip. It opens only in edit mode, on a report you can edit.
• The header counts its entries, such as Diagnostics (3). The empty state reads No entries yet, and Close diagnostics closes it.
• Entries carry a time and one of five levels: log, warn, error, violation or host. Warnings are amber; errors and violations are red.

Questions, answered

How do I open the Studio for a library visual?

Open the visual from the visual library (DataPrism > Visuals) and select Edit code. You need the Author DataPrism Custom Visuals permission; if the button is not there, ask an administrator. See Who can do what in DataPrism.

Why is Save as new version disabled?

Either the draft is not valid yet (one of the JSON files does not parse) or there is nothing new to save. With no changes, its tooltip reads No changes to save.

Does saving a version publish it?

No. Saving adds a new version; the published version moves only when you publish it from the library. See Custom visuals and the visual library.

The tile says "Paused to keep the page responsive". What does that mean?

The report paused this visual to stay responsive, and shows a faded snapshot of its last rendered state. Select Activate to run it again.

Why does a card show "Preview unavailable"?

The preview image could not be captured for that card, so the card shows the fallback text in its place.

Why is the diagnostics drawer empty?

It reads No entries yet when the tile has not reported anything yet. Refresh the report or the tile, then open the drawer again once the visual has rendered.

Why can I not open the diagnostics drawer?

It opens only in edit mode, on a report you can edit. Switch the report into edit mode first; if you cannot, ask an administrator for edit access.

Why does my report warn about a large asset?

A file above 2 MB is marked large, because every frame that references it downloads its own copy. The dialog also warns when the report's files would pass the 8.0 MB a visual may transfer. Compress or remove the files you do not need.

How do I use an uploaded file in my visual's code?

Reference it as asset://file-name in markup or CSS, or by file name in a uni.assets call. uni.assets.url(name) gives its blob URL and uni.assets.bytes(name) its bytes. Copy reference to {fileName} on the card copies the reference for you.

Why does a visual show an asset as missing?

The file was deleted from the report, or its stored file cannot be read. The card reads File missing or Could not load, and visuals referencing it show it as missing. Upload the file to the report again to restore it.

What does "SVG sanitised" mean?

The SVG you uploaded carried <style> or <foreignObject>. Those parts were removed before the file was stored, so it may render differently from the original. Check it in the preview and adjust the file if needed.

Does the AI panel work on more than one tile at a time?

Each tile keeps one conversation. Starting another on the same tile opens the existing thread instead of a second one.