OpenDoc Pre-release
GitHub Open the editor

SDK · Embedding

Configure an embed, and watch it change

The editor beside these controls is running right now, configured by them. Change a role, withhold a capability, take a chrome region away or give it a brand colour, and it becomes the thing you configured — then copy the configuration that reproduces exactly what is on screen.

Role

A name for a subset of the capability set, never the unit of enforcement. Switching one rewrites everything below it.

  • A picture of the document — a thumbnail, an attachment preview, a print preview. 0/9 capabilities 0/25 regions viewing
  • A published document, to read. 1/9 capabilities 10/25 regions viewing
  • Google Docs' Commenter, Word's reviewer. 3/9 capabilities 24/25 regions suggesting
  • The reason a host embeds an editor. 6/9 capabilities 24/25 regions editing
  • The page is ours, or the host has said it may as well be. 9/9 capabilities 25/25 regions editing

Changes the document and keeps it; may not reach for a different one, and advertises nothing of ours. Grants save download print edit comment autosave Chrome regions offered 24/25

Capabilities

Withheld one at a time. A list can only narrow a role, so a capability the role never granted is struck through and disabled.

Getting documents in and out5
  • Replace the loaded document from inside the editor.
  • Start a blank document.
  • Write the document back out.
  • Export to a file the visitor keeps.
  • Open the browser's print dialog.
Changing the document2
  • Change the document at all.
  • Annotate, and change the document as tracked suggestions.
Inside the frame2
  • Show OpenDoc's own name and mark inside the frame.
  • Keep drafts of the visitor's typing on this origin.
Chrome regions

Whole presentations a host can decline, 8 of them ribbon bands. Dropping ribbon drops every band with it.

Top bar6
  • Our name and mark in the top bar.
  • The document name, and renaming it.
  • The document-state chips and Document properties in the top bar.
  • The Editing / Suggesting / Read-only switcher in the top bar.
  • The application menu bar — one of the two navigation axes.
  • The whole tabbed ribbon, strip and bands together.
Ribbon bands8
  • The File page: open, save, export, print, properties, settings.
  • Character and paragraph formatting, styles, clipboard, undo.
  • Tables, pictures, shapes, links, comments, headers, symbols.
  • Page setup, margins, columns, spacing, watermark, arrange.
  • Captions, cross-references, contents, footnotes, fields.
  • Tracked changes, comments, proofing, the review mode control.
  • Outline, zoom, page setup, showing changes.
  • The contextual table band, present when the caret is in a table.
Beside the document6
  • The left navigation rail: outline and page thumbnails.
  • The ruler strip above the page: indents and tab stops.
  • The text caret and the selection highlight on the page.
  • The right-click menu on the document.
  • Object selection: the outline, its handles and the object bar.
  • The version-history timeline, its ribbon entry and its preview bar.
Status bar2
  • The status bar: counts, page number, language, mode.
  • The zoom cluster in the status bar.
Overlays3
  • The find and replace card.
  • The floating toolbar above a selection.
  • The settings dialog and the gear that opens it.
Brand

The palette tokens are a public contract; geometry and the paper layer are refused. These apply to the running editor with no reload.

The live editor

  • —
  • — of 9 capabilities
  • — of 25 regions shown
    What the frame is given
    Chrome withheld
    —
    Frame sandbox
    —

    The editor holds a WebAssembly instance of roughly 100 MB and is booting now. The readout above is already live: it is resolved from the same authority the editor resolves.

    The configuration this produces

    Both panels are rewritten on every change, and between them they are the whole of what a host writes. The element takes 8 attributes, and everything configured above has one: mode names the role, can withholds capabilities and chrome withholds regions. Both lists only ever narrow — nothing here can hand a role something it was not given, which is the property the whole model rests on. The element writes them into the frame's URL before its first navigation, so the same decisions are also expressible as the parameters autosave mode can chrome prefs granted participant room for a host with no package at all.

    The embed — paste this into your page
    webapp/brand.json — then run node webapp/tools/build-brand.mjs

    A colour that fails WCAG AA is refused by that command, naming the pair, the measured ratio, the floor and the nearest value on the same hue that would pass — not corrected, because a product shipped in an accent nobody approved is a lie a host discovers from a screenshot, and not warned about, because a warning in a build log is ONLYOFFICE's nag-modal in a different font. The floors are WCAG's own split: 4.5:1 for text, 3:1 for edges and icons. The refusal beside the Brand controls is produced by the same code that command runs, in this page, so it cannot describe a message the generator no longer emits.

    The rules these controls follow

    Nothing here is gated. ONLYOFFICE puts host customization behind a licence check in code — LayoutManager._applyCustomization returns early when !_licensed — so an integrator ships their chrome and then discovers the modal. This is Apache-2.0, the permissive licence is the whole point of the project, and gating the one thing that makes it worth embedding would surrender it.

    A capability list narrows; it never widens. All 9 are withheld independently — “comments only, everything else off” is a configuration, not a rung on a ladder — but a list can only take away from what the role granted, so there is exactly one direction to audit.

    A region is not a capability. Withholding a region is a decision about your page; withholding a capability is a permission. That is why preview and readonly are different presentations rather than one with print turned off, and why the region list narrows the same way the capability list does.

    A palette is a stylesheet. The brand fields apply to the running editor with no reload, because a white-labelled build is one swapped stylesheet. Everything else here is resolved before the frame's first navigation, so it remounts instead.

    What this page does not do yet

    The reference for all of it is Embed the editor: the capability table, the region table, the host contract, the refusal codes, and the tests that hold each claim up.