--- title: "The Studio Code View · RUAL Documentation" description: "The Canvas and Code switch in RUAL Studio: Check, Stage to canvas, Place unpositioned, the Positions toggle and what each message means." canonical: https://docs.rual.nl/engine/studio-code-view language: en --- [Cluster](https://docs.rual.nl/cluster) [Blocks](https://docs.rual.nl/block-types) [Interfaces](https://docs.rual.nl/interfaces) [Blueprints](https://docs.rual.nl/blueprints) [Blueprint Language](https://docs.rual.nl/engine) [Tutorials](https://docs.rual.nl/tutorials) [Home automation](https://docs.rual.nl/home-automation) [Examples](https://docs.rual.nl/examples) [Reference](https://docs.rual.nl/reference) [Architecture](https://docs.rual.nl/architecture) [Troubleshooting](https://docs.rual.nl/troubleshooting) Other # The Studio Code View RUAL Studio shows a blueprint two ways: the canvas, and its [Blueprint Language](https://docs.rual.nl/engine/blueprint-language) source in a code editor. An edit in the code view is checked by the same compile as the [source API](https://docs.rual.nl/engine/editing-with-ai) and staged on the canvas as unsaved edits, which you review and save there. ## Canvas and Code are two views of one blueprint The blueprint header has a **Canvas** | **Code** switch. Code opens the source over the canvas; the canvas stays loaded underneath, so switching back is instant. Each time you switch to Code without an edit in progress, the view exports the blueprint again, as the canvas shows it (unsaved edits included), so the source always matches what you were just looking at. The code view is new. When the blueprint header shows no Canvas and Code switch, your Studio does not include it yet. ## Edit a blueprint in the code view - Open the blueprint and switch to **Code**. - Edit the source. The title bar shows **Edited** as soon as the text differs from the export. - Press **Check** (Cmd+Enter on a Mac, Ctrl+Enter elsewhere). Errors and warnings are marked on their lines, and the status bar summarises the diff, for example `8 new, 3 changed`. - Fix every marked error and Check again until it says *Compiles cleanly.* or *Compiles, with warnings on the marked lines.* - Press **Stage to canvas** (Cmd+S or Ctrl+S). The status bar says *Staged 11 changes on the canvas. Review and save them there.* and the source reloads with the new blocks' real identities. - Switch to **Canvas**, review the staged edits, simulate if that helps, and save. Nothing is live before that save. ## The toolbar The title reads *Blueprint Language*, followed by the size of the export (for example `24 blocks · 4.5% of its JSON`) and the **Edited** or **Read only** badge. | Button | What it does | When it is available | | --- | --- | --- | | **Positions** | Shows or hides each block's canvas position as a [`// @xy X,Y`](https://docs.rual.nl/engine/blueprint-language#positions) pragma, and exports again. Pragmas are coloured apart from ordinary comments. The choice is remembered in your browser; positions are on by default. | Not while the source is edited: stage or reload first. | | **Place unpositioned** | Lays out only the blocks that have no position, around everything else, and stages those positions as unsaved edits. Answers *Every block already has a position.* when there is nothing to place. | With edit rights, when the source is not edited. | | **Reload** | Exports the blueprint again as the canvas shows it now, replacing the editor's text. | Always. | | **Check** | Compiles the source against the canvas (a [dry run](https://docs.rual.nl/engine/editing-with-ai#step-3)), marks errors and warnings on their lines and shows the diff as counts of new, changed, moved and removed blocks. Writes nothing. | Always, read-only included. Cmd+Enter or Ctrl+Enter. | | **Stage to canvas** | Compiles the source and [stages](https://docs.rual.nl/engine/editing-with-ai#step-4) the diff on the canvas as unsaved edits, then reloads the source. | With edit rights, when the source is edited. Cmd+S or Ctrl+S. | While a stage, a placement or a reload is running, the editor does not take typing: each of them ends by replacing the text. The editor also stays locked until an export has loaded, so an empty editor can never be staged. ## Read only without edit rights Staging writes unsaved edits like any canvas edit, so it needs the `setting_edit_blueprints` permission. Without it, and while you look at an older revision, the view is read only: you can read, Check and reload the source, but **Place unpositioned** and **Stage to canvas** are hidden. ## What a refused stage says A stage writes all of its changes or none. When it is refused, the status bar says why and your edit stays in the editor: | Cause | Status bar | | --- | --- | | The source has errors | *Fix 2 errors before staging.* | | Blocks the edit touches changed on the canvas after the source was loaded (`SOURCE_STALE`) | *1 block this edit touches changed on the canvas since the source was loaded. Nothing was staged: copy your edit, reload, and apply it again.* | | Another user has unsaved edits on a block the edit touches (`FOREIGN_OVERLAY`) | *Another user has staged changes on 1 block this edit touches. Nothing was staged: they save or discard first.* | | The edit adds blocks and the account may not create blocks | *This edit adds blocks, and your account may not create blocks in this blueprint. Nothing was staged.* | | A write failed and was undone (`rolled_back`) | *1 block could not be written, so nothing was staged. Your edit is kept; try Stage again.* | | The source equals the canvas | *Nothing to stage: the source matches the canvas.* | The counts in these messages follow the answer: *1 block*, *3 blocks* and so on. ## The code view uses the public source API Every button is one request to the cluster, the same requests an [AI agent](https://docs.rual.nl/engine/editing-with-ai) makes: | Button | Request | | --- | --- | | Opening Code, Reload, Positions | `GET /api/v1/blueprints/{guid}/source?view=staged&positions=1` (`positions=0` with Positions off) | | Check | `POST /api/v1/blueprints/{guid}/source?dry_run=1&view=staged` with the source and the lock of the export | | Stage to canvas | `POST /api/v1/blueprints/{guid}/source?stage=1&view=staged` with the source, the lock, the export's `update_hashes` and `source_view` | | Place unpositioned | `POST /api/v1/blueprintactions/layout/{guid}` with `{"unpositioned": true}` | - [Editing Blueprints with an AI Agent](https://docs.rual.nl/engine/editing-with-ai): The requests behind these buttons, with their responses. - [RUAL Studio](https://docs.rual.nl/interfaces/rual-studio): The rest of the cluster management interface. ## Frequently asked **How do I edit a RUAL blueprint as code in the Studio?** Open the blueprint, switch the header from Canvas to Code, and edit the Blueprint Language source. Press Check (Cmd or Ctrl+Enter) to compile it and see errors on their lines, then Stage to canvas (Cmd or Ctrl+S) to put the change on the canvas as unsaved edits, and save it there. **Why is the RUAL code view read only?** Staging from the code view writes unsaved edits like any canvas edit, so it needs the setting_edit_blueprints permission. Without it, or while you look at an older revision, you can read and Check the source but Stage to canvas and Place unpositioned are hidden. Was this page helpful? [Tell us what to improve](https://docs.rual.nl/support) · RUAL Docs is an integral component of the [RUAL ecosystem](https://rual.nl)