Read, replace and validate content
Choose between insertion, body replacement and opening a document, while preserving the original input.
Before loading server data, establish which document model it belongs to. HTML, JSON and Markdown represent content; none installs the nodes, marks or conversion rules required to understand it.
Choose a representation
| Content | Usage | Considerations |
|---|---|---|
| JSON | content: { type: 'doc', content: [...] } | Preserve your product's structure and restore with a compatible Schema |
| HTML | content: '<p>Hello</p>' | Strings default to HTML parsing, requiring a DOM and extension parsing rules |
| Markdown | content: '# Hello', contentType: 'markdown' | Select the type explicitly; conversion depends on rules provided by installed extensions |
getJSON() reads canonical structure, getText() reads plain text, getHTML() uses the Schema's HTML serializers, and getMarkdown() uses the Markdown manager. HTML output requires a browser DOM and excludes paginated surfaces, product toolbars and screenshots. Custom nodes need rules for each required format; matching visible text alone does not prove fidelity.
Choose the intended operation
| Task | Call | Result |
|---|---|---|
| Add content at the current selection | commands.insertContent(content) | Insert or replace the selection through ordinary edit history |
| Replace the current document body | commands.setContent(content, options) | Replace child content while retaining top-node attributes |
| Open a complete document | commands.replaceDocument(content, options) | Restore root attributes, move selection to the start, and exclude this replacement from history |
Word document settings and style registries live in root attributes, while section nodes represent sections in the body, so restoring files requires more than setContent(). Excluding a replacement from history does not establish a fresh editing session: isolate old tasks, subscriptions and history policy when changing business documents. Create a new Editor for a definite session boundary; Classic can replace its document configuration.
const accepted = editor.commands.replaceDocument(content, {
errorOnInvalidContent: true,
emitUpdate: false,
})
errorOnInvalidContent: true makes invalid parsing throw, so catch errors. emitUpdate: false suppresses content update notifications; replacement and transaction processing still occur. It can support restoration that explicitly establishes a saved baseline, but does not silence every side effect.
Validate before replacing
Validate the application's model/version, node/mark/attribute names, and Schema content rules. Calling check() on a parsed node validates structure, but parsing may already have discarded unknown attributes. Consequently, schema.nodeFromJSON(value).check() alone cannot prove that the original input lost no fields.
Keep the original input and reject unknown fields or migrate them explicitly before conversion. The reference's files/backup.ts checks names before parsing, then validates the root and child content; see file operations. On failure, retain the current draft rather than saving fallback empty content over the source.
Creation options enableContentCheck / emitContentError report initial content errors. Construction may still establish fallback content, so successful construction does not prove a successful import. Strict restoration validates first and commits afterward.
Updates and saving state
setEditable() also emits update by default without changing the document. Compare previous and current documents when tracking unsaved changes; see lifecycle and events. When saving finishes, confirm that the current document is still the submitted revision; see persistence.
Full parameter definitions are in Editor options and events.