HTML Shell

warning

Experimental. This feature may change or be removed.

The shell is the single HTML file that fills the Custom Dashboard canvas. TagoIO hosts it for you (versioned storage). You do not host a public URL for the dashboard page itself.

There is no in-app HTML editor. Edit the file offline, then upload again.

First upload

Until a shell exists, the dashboard shows an empty state:

• Upload HTML to choose a local .html file.
• A collapsible note with the postMessage snippet so you can wire dashboard:ready correctly.

After a successful upload, Admin loads the shell in an iframe and waits for your page to signal ready.

Gear menu (shell actions)

When the dashboard is a Custom Dashboard, the gear menu includes shell actions that Normal and Blueprint dashboards do not have:

Action	What it does
Upload new HTML	Replace the current shell with another local file.
Download current HTML	Save the hosted shell as a local .html file for offline edit.
Data source	Open the optional bound source settings. See Data sources.

Use download, edit locally, then upload new HTML as the normal edit loop.

Header refresh

After a shell exists, the dashboard header shows a data refresh control. It re-runs the bound data load and posts a fresh dashboard:data (and theme) to the iframe. It does not re-upload or rewrite the HTML file.

Version restore

Dashboard version restore works for the shell. Restoring a version can return a previous HTML upload (or clear the shell if that version had none). After restore, Admin reloads the canvas to match what is stored.

Setup for the optional data source is part of the dashboard record; restore behavior follows the same version tooling as other dashboard fields.

API surface (shell)

Most authors stay in Admin. If you automate shell upload:

Method	Path	Notes
PUT	/dashboard/{id}/html	Body is raw HTML (Content-Type: text/html). Profile token required.
GET	/dashboard/{id}/html	Returns the hosted shell. Auth via short-lived html_access (exp + sig) from dashboard info, or a token query parameter.

Full request details live in the TagoIO API reference under dashboards.

Tips

• Ship a single file: inline CSS and JS, or load third-party assets from absolute HTTPS URLs your page is allowed to use.
• Post dashboard:ready only after listeners are registered so you do not miss the first data message. See Authoring HTML.
• Prefer download + re-upload over hand-editing production shells from memory.