Skip to content
API documentationv1

Editor embedding

Configuration reference

Every config field: document, editor, ui, token and events, with types, defaults, the document.key rules and the invalid_config error.

On this page

new O3O.Editor(elementId, config) takes the container id (or the DOM element itself) and a config object with four groups: document, editor, ui, token, plus events, which stays in the browser. The constructor returns at once; the session is created asynchronously and errors go through onError.

  • Element not found: the constructor throws Error("O3O.Editor: không tìm thấy phần tử ...").
  • Each container holds ONE editor. Calling the constructor again on the same element before destroy() throws.
  • The container needs a real height (for example height: 100vh) because the frame defaults to 100%.
JavaScriptFull configuration
const config = {
  document: {
    url: "https://files.example.com/contracts/42.docx",   // the gate downloads the source file from here
    title: "Contract 42.docx",
    fileType: "docx",
    key: "contract-42-v7"                                   // identifies a content VERSION
  },
  editor: {
    mode: "edit",                                           // "edit" | "view"
    lang: "en-US",
    user: { id: "u-1001", name: "Jane Doe" },
    callbackUrl: "https://app.example.com/o3o/callback"
  },
  ui: {
    width: "100%",
    height: "100%",
    mode: "tabbed",                                         // "tabbed" | "compact"
    closeButton: true,
    saveButton: true,
    print: true,
    export: true,
    copy: true,
    userList: true,
    statusbar: true,
    menubar: false,
    limitBanner: true
  },
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",          // required when the server sets O3O_EMBED_JWT_SECRET
  events: {
    onSaved: (e) => console.log(e.version)
  }
};

const editor = new O3O.Editor("o3o-editor", config);

document#

document (required)

  • document.urlstring (URL)required
    http or https URL the GATE downloads the source file from. Subject to the SSRF rules. The browser never fetches it.
  • document.titlestring, 1–255 charsrequired
    Display name. Without an extension the gate appends . + fileType. The nine characters forbidden in Windows file names and control characters become _.
  • document.fileTypestringrequired
    One of docx, doc, odt, rtf, txt, xlsx, xls, ods, csv, pptx, ppt, odp. Lower case, no dot.
  • document.keystringrequired
    Identifies a content VERSION, matches ^[A-Za-z0-9._-]{1,128}$. Everyone opening the same key edits one shared document. See the rules below.

Rules for document.key#

  • The gate downloads document.url only for the FIRST user of a key; later users join the open copy and their url is ignored.
  • After the closed callback, the next open MUST use a new key (append a version number or the file's modification time).
  • Reusing an old key within the retention time (24 hours) reopens the last working copy the gate holds, WITHOUT downloading url again.
  • Internal document id: doc_id = "doc_" + first 32 hex chars of SHA-256(key).

editor#

editor (required)

  • editor.mode"edit" | "view"optionalDefault: "edit"
    view is read-only and is NOT counted as a connection.
  • editor.langstringoptionalDefault: "vi"
    Interface language code, e.g. vi, en-US.
  • editor.user.idstring, 1–64 charsrequired
    User id in your system.
  • editor.user.namestring, 1–128 charsoptionalDefault: "Khách"
    Display name in the co-editor list.
  • editor.callbackUrlstring (URL)optional
    Where the gate sends callbacks when a new version is saved (see saving and callbacks). Subject to the SSRF rules. Without it, edited copies stay on the gate for the retention time and the page gets them through onSaved.

ui#

Optional. Leaving a field out keeps the editor server default. The table lists only what v1 actually implements.

ui (optional)

  • ui.widthCSS stringoptionalDefault: "100%"
    Frame width.
  • ui.heightCSS stringoptionalDefault: "100%"
    Frame height. The container must have a real height.
  • ui.mode"tabbed" | "compact"optionalDefault: "tabbed"
    Tabbed or compact toolbar.
  • ui.closeButtonbooleanoptionalDefault: false
    Shows a close button; clicking it fires onClose.
  • ui.saveButtonbooleanoptionalDefault: true
    false hides the save command (autosave still runs).
  • ui.printbooleanoptionalDefault: true
    false hides and blocks printing.
  • ui.exportbooleanoptionalDefault: true
    false hides and blocks downloading in other formats.
  • ui.copybooleanoptionalDefault: true
    false blocks copying content out of the frame.
  • ui.userListbooleanoptionalDefault: true
    Shows the co-editor list.
  • ui.statusbarbooleanoptionalDefault: server default
    Status bar, applied once the document has loaded.
  • ui.menubarbooleanoptionalDefault: server default
    Menu bar, only meaningful with mode: "compact"; applied after loading.
  • ui.limitBannerbooleanoptionalDefault: true
    Vietnamese banner that api.js draws above the frame when a session is downgraded to read-only by the cap.
Coming soon

theme (light, dark), logo, productName, primaryColor (white label, enterprise edition with the source-built O3O image), watermark, per-button visibility, ruler, sidebar. v1 ignores these fields and prints a console warning.

token and events#

Remaining fields

  • tokenstring (JWT)optional
    Optional on DEV machines, REQUIRED when the server sets O3O_EMBED_JWT_SECRET. With a valid token the gate uses document, editor, ui FROM the token. See signing the config.
  • eventsobjectoptional
    Callback functions, see events. Never sent to the server.

When the config is invalid#

The gate validates the config before anything else. Missing or wrong fields give 400 invalid_config with a list in detail.errors shaped as {path, message}, and onError fires with the same code. The message wording below is illustrative.

400invalid_config
{
  "error": {
    "code": "invalid_config",
    "message": "Cấu hình trình soạn thảo không hợp lệ.",
    "detail": {
      "errors": [
        {
          "path": "document.key",
          "message": "Chỉ gồm chữ, số, dấu chấm, gạch dưới, gạch nối; tối đa 128 ký tự."
        }
      ]
    },
    "request_id": "req_0123456789abcdef"
  }
}

Report a problem or suggest an editO3O Office Online · API v1 · Page version 26.8.6