Embed a model in your site#
This guide shows you how to embed a Simcraft model in your page. Readers can run the model and open it in Simcraft, but they can't change it.
An embed is an <iframe>. Your page needs no Simcraft code and no build step. You share the model first, because only a shared model can be embedded.
Intended use#
Use an embed on a page about a model: a lesson, a course page, a post, or an explanation of how a system behaves. Your readers run the model where they would otherwise see a picture of it.
If you're building an application on simulation, an <iframe> is the wrong tool. Use the WebAssembly engine, the TypeScript client, or the Python SDK, which run a document and give you its event stream. See the reference implementation.
Share the model, then copy the snippet#
- Open the model in Simcraft and press Share.
- Turn on Share with anyone who has the link.
- Copy the snippet beside Embed.
The snippet looks like this:
<iframe
src="https://app.simcraft.io/embed/models/7a1f4d2e-9c3b-4f55-8e21-6d4a0b9c7e13"
title="Clinic"
width="100%"
height="520"
style="border:0"
></iframe>Paste it into your page. The frame fills the width of its column. An <iframe> doesn't grow to fit its content, so you set the height.
Screen readers announce the frame by its title, which the snippet sets to the model's name. Change it if your page calls the model something else.
If you turn sharing off, the embed stops loading and says the model is not shared.
Settings#
Add settings to the embed address as query parameters. Each one changes what readers see.
| Parameter | Values | Default | Effect |
|---|---|---|---|
header | 1, 0 | 1 | The bar with the model's title, a View only label, and Open in Simcraft |
controls | 1, 0 | 1 | The run bar, which plays, steps, and resets the run, and opens its results |
inspect | 1, 0 | 1 | The Inspect panel, which opens when the reader selects a component |
code | 1, 0 | 0 | A Code button in the header, which shows the model's OSDL |
theme | light, dark, auto | auto | The theme. auto follows the reader's system setting and changes with it |
experiment | an experiment's name | the model's first | The experiment the page opens with |
autorun | 1, 0 | 0 | Whether the run starts as the page loads |
This snippet runs the model as the page loads, with no header and no Inspect panel:
<iframe
src="https://app.simcraft.io/embed/models/7a1f4d2e-9c3b-4f55-8e21-6d4a0b9c7e13?header=0&inspect=0&autorun=1"
title="Clinic"
width="100%"
height="320"
style="border:0"
></iframe>With header=0 there is no Code button, so code=1 opens the embed in the code view. The code view hides the run bar, so readers of that embed can't run the model.
If the model has no experiment with the experiment name, the embed opens the model's first experiment.
A value that isn't in this table leaves the setting at its default, so a typo in the address still shows the model.
Size#
Make the frame at least 320 by 420 pixels. Below that, the diagram is too small to read.
These measurements use the quickstart's M/M/1 queue. The diagram's height is the space between the header and the run bar.
| Frame | Header | Diagram |
|---|---|---|
| 400 × 520 | two rows, 70px | 310px |
| 320 × 420 | two rows, 70px | 160px |
| 400 × 320 | two rows, 70px | 110px |
| 860 × 560 | one row, 45px | 395px |
At 420 pixels wide or less, the header puts its buttons on a second line under the title. The run bar fits at every size in the table. It is 80 pixels tall in the 860-pixel frame, and 100 pixels tall, in two rows, in the narrower frames.
A shorter frame works if readers don't need to run the model. Set controls=0 to show the diagram alone, and add autorun=1 to animate it.
Readers open a run's results with Results in the run bar. The embed never opens them by itself, because they would cover the model. In a frame narrower than 760 pixels the results fill the frame, and their close button returns to the model.
Limits#
The model must be shared#
You can embed only a shared model. For a private or deleted model, the embed says the model is not shared.
Readers cannot edit#
Every embed is view-only, and no setting changes that. To change the model, a reader presses Make a copy in the Inspect panel, which opens their own copy in a new tab. Open in Simcraft opens the model view-only in the app, where they can also make a copy. Your model never changes.
The run happens in the reader's browser#
An embed runs the model in the reader's browser, on the WebAssembly engine. A run needs no account and sends nothing to a server. If the browser can't load the engine, the embed says so. It never falls back to a server.
The read limit for each network#
Each embed that loads counts as one read of a shared model, and so does each visit to a model's link. Simcraft allows 60 reads a minute from one IP address. Over the limit, a reader sees "Too many requests. Try again in a minute.", and the embed loads if they reload a minute later. A class on one school network can reach the limit by opening a page with several embeds.
Simcraft is pre-alpha. The embed address, its settings, and the frame's appearance can all change.