Editor embedding
Modes and permissions
The edit and view modes, how they count as connections, the print, export and copy switches, and co-editing with mixed modes.
The v1 embed layer has two modes and a set of interface switches. Real permissions (who may open which file) are decided by your server when it signs the config; O3O only enforces what the config says.
Two modes#
| editor.mode | The user can | Counts as a connection | Notes |
|---|---|---|---|
edit | View, edit, save, co-edit | Yes, 1 connection per session | At the cap, new sessions are downgraded to view. |
view | View only (plus print, download, copy if ui allows) | No | Always opens, even at the cap. |
One person editing three documents is three connections; three people co-editing one document is also three connections. Details: connection counting.
Interface switches#
| ui field | Matching WOPI property | Effect when false |
|---|---|---|
print | HidePrintOption, DisablePrint | Hides and blocks printing. |
export | HideExportOption, DisableExport | Hides and blocks downloading in other formats. |
copy | DisableCopy | Blocks copying content out of the frame. |
saveButton | HideSaveOption | Hides the save command; autosave still runs. |
userList | HideUserList | Hides the co-editor list. |
closeButton (true) | ClosePostMessage | (when true) shows a close button and fires onClose. |
Co-editing and mixed modes#
All sessions sharing a document.key work on one document, each with its own editor.user.id. Editors and viewers can mix: viewers see the editors' changes in real time.
<div id="editor-a" style="height: 45vh"></div>
<div id="editor-b" style="height: 45vh"></div>
<script src="http://localhost:8080/o3o/api.js"></script>
<script>
// Same key = same document. An edits (1 connection), Binh only views (not counted).
const doc = { url: "http://localhost:8080/o3o/demo/sample.docx", title: "sample.docx", fileType: "docx", key: "coedit-demo-1" };
new O3O.Editor("editor-a", { document: doc, editor: { mode: "edit", lang: "en-US", user: { id: "u-an", name: "An" } } });
new O3O.Editor("editor-b", {
document: doc,
editor: { mode: "view", lang: "en-US", user: { id: "u-binh", name: "Bình" } },
ui: { print: false, export: false, copy: false } // the viewer cannot print, download or copy out
});
</script>Switch modes while open#
editor.setReadOnly(true | false) saves pending changes, switches the mode on the gate (POST /o3o/embed/session/{id}/mode) and reloads the frame. Switching to edit applies the connection cap.
document.getElementById("toggle").onchange = async (ev) => {
const { mode } = await editor.setReadOnly(!ev.target.checked); // saves pending changes, then reloads the frame
if (ev.target.checked && mode === "view") {
ev.target.checked = false; // cap reached: still read-only, onLimitReached has fired
}
};