Creates an empty document instance with no #roots (other than the #graveyard graveyard root).
ReadonlydifferThe model differ object. Its role is to buffer changes done on the model document and then calculate a diff of those changes.
ReadonlyhistoryThe document's history.
ReadonlyisDefines whether the document is in a read-only mode.
The user should not be able to change the data of a document that is read-only.
ReadonlymodelThe module:engine/model/model~Model model that the document is a part of.
ReadonlyrootsA list of roots that are owned and managed by this document. Use #createRoot, #getRoot and #getRootNames to manipulate it.
ReadonlyselectionThe selection in this document.
The graveyard tree root. A document always has a graveyard root that stores removed nodes.
The document version. Every applied operation increases the version number. It is used to ensure that operations are applied on a proper document version.
This property is equal to module:engine/model/history~History#version model.Document#history#version.
If the module:engine/model/operation/operation~Operation#baseVersion base version does not match the document version, a module:utils/ckeditorerror~CKEditorError model-document-applyoperation-wrong-version error is thrown.
Internal
Returns the default range for this selection. The default range is a collapsed range that starts and ends at the beginning of this selection's document #_getDefaultRoot default root.
Protected_Returns the default root for this document which is either the first root that was added to the document using #createRoot or the #graveyard graveyard root if no other roots were created.
The default root for this document.
Internal
Check if there were any changes done on document, and if so, call post-fixers,
fire change event for features and conversion and then reset the differ.
Fire change:data event when at least one operation or buffered marker changes the data.
The writer on which post-fixers will be called.
Protected_Returns whether there is a buffered change or if the selection has changed from the last
module:engine/model/model~Model#enqueueChange enqueueChange() block
or module:engine/model/model~Model#change change() block.
Returns true if document has changed from the last change() or enqueueChange() block.
Internal
Checks whether a given module:engine/model/range~ModelRange range is a valid range for the #selection document's selection.
A range to check.
true if range is valid, false otherwise.
Creates a new root.
Note: do not use this method after the editor has been initialized! If you want to dynamically add a root, use
module:engine/model/writer~ModelWriter#addRoot model.Writer#addRoot instead.
Note: The default elementName value is '$root'. When the editor uses a custom root
module:core/editor/editorconfig~RootConfig#modelElement modelElement, pass the configured model element
name explicitly so the created root matches the schema the features expect.
See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
{@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
OptionalelementName: string
The element name. Defaults to '$root' which also has some basic schema defined
(e.g. $block elements are allowed inside the $root). Make sure to define a proper schema if you use a different name.
OptionalrootName: string
A unique root name.
The created root.
Removes all event listeners set by the document instance.
Returns a root by its name.
Detached roots are returned by this method. This is to be able to operate on the detached root (for example, to be able to create a position inside such a root for undo feature purposes).
Optionalname: string
The root name of the root to return.
The root registered under a given name or null when there is no root with the given name.
Returns an array with names of all roots added to the document (except the #graveyard graveyard root).
Detached roots are not returned by this method by default. This is to make sure that all features or algorithms that operate on the document data know which roots are still a part of the document and should be processed.
OptionalincludeDetached: boolean
Specified whether detached roots should be returned as well.
Returns an array with all roots added to the document (except the #graveyard graveyard root).
Detached roots are not returned by this method by default. This is to make sure that all features or algorithms that operate on the document data know which roots are still a part of the document and should be processed.
OptionalincludeDetached: boolean
Specified whether detached roots should be returned as well.
Used to register a post-fixer callback. A post-fixer mechanism guarantees that the features will operate on a correct model state.
An execution of a feature may lead to an incorrect document tree state. The callbacks are used to fix the document tree after
it has changed. Post-fixers are fired just after all changes from the outermost change block were applied but
before the module:engine/model/document~ModelDocument#event:change change event is fired. If a post-fixer callback made
a change, it should return true. When this happens, all post-fixers are fired again to check if something else should
not be fixed in the new document tree state.
As a parameter, a post-fixer callback receives a module:engine/model/writer~ModelWriter writer instance connected with the executed changes block. Thanks to that, all changes done by the callback will be added to the same module:engine/model/batch~Batch batch (and undo step) as the original changes. This makes post-fixer changes transparent for the user.
An example of a post-fixer is a callback that checks if all the data were removed from the editor. If so, the callback should add an empty paragraph so that the editor is never empty:
document.registerPostFixer( writer => {
const changes = document.differ.getChanges();
// Check if the changes lead to an empty root in the editor.
for ( const entry of changes ) {
if ( entry.type == 'remove' && entry.position.root.isEmpty ) {
writer.insertElement( 'paragraph', entry.position.root, 0 );
// It is fine to return early, even if multiple roots would need to be fixed.
// All post-fixers will be fired again, so if there are more empty roots, those will be fixed, too.
return true;
}
}
return false;
} );
A custom toJSON() method to solve child-parent circular dependencies.
A clone of this object with the document property changed to a string.
Data model's document. It contains the model's structure, its selection and the history of changes.
Read more about working with the model in {@glink framework/architecture/editing-engine#model introduction to the the editing engine's architecture}.
Usually, the document contains just one module:engine/model/document~ModelDocument#roots root element, so you can retrieve it by just calling module:engine/model/document~ModelDocument#getRoot without specifying its name:
However, the document may contain multiple roots – e.g. when the editor has multiple editable areas (e.g. a title and a body of a message).