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.
InternalReturns 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.
InternalCheck 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.
InternalChecks 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.
OptionalelementName: stringThe 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: stringA unique root name.
The created root.
Delegates selected events to another module:utils/emittermixin~Emitter. For instance:
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
then eventX is delegated (fired by) emitterB and emitterC along with data:
emitterA.fire( 'eventX', data );
and eventY is delegated (fired by) emitterC along with data:
emitterA.fire( 'eventY', data );
Event names that will be delegated to another emitter.
Removes all event listeners set by the document instance.
Fires an event, executing all callbacks registered for it.
The first parameter passed to callbacks is an module:utils/eventinfo~EventInfo object,
followed by the optional args provided in the fire() method call.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The name of the event or EventInfo object if event is delegated.
Additional arguments to be passed to the callbacks.
By default the method returns undefined. However, the return value can be changed by listeners
through modification of the module:utils/eventinfo~EventInfo#return evt.return's property (the event info
is the first param of every callback).
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: stringThe 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: booleanSpecified 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: booleanSpecified whether detached roots should be returned as well.
Registers a callback function to be executed when an event is fired in a specific (emitter) object.
Events can be grouped in namespaces using :.
When namespaced event is fired, it additionally fires all callbacks for that namespace.
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );
// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
An event callback can module:utils/eventinfo~EventInfo#stop stop the event and set the module:utils/eventinfo~EventInfo#return return value of the #fire method.
The type describing the event. See module:utils/emittermixin~BaseEvent.
The object that fires the event.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Stops executing the callback on the given event.
Shorthand for #stopListening this.stopListening( this, event, callback ).
The name of the event.
The function to stop being called.
Registers a callback function to be executed when an event is fired.
Shorthand for #listenTo this.listenTo( this, event, callback, options ) (it makes the emitter
listen on itself).
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
Registers a callback function to be executed on the next time the event is fired only. This is similar to calling #on followed by #off in the callback.
The type descibing the event. See module:utils/emittermixin~BaseEvent.
The name of the event.
The function to be called on event.
Optionaloptions: GetCallbackOptions<TEvent>Additional options.
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;
} );
Stops delegating events. It can be used at different levels:
Optionalevent: stringThe name of the event to stop delegating. If omitted, stops it all delegations.
Optionalemitter: Emitter(requires event) The object to stop delegating a particular event to.
If omitted, stops delegation of event to all emitters.
Stops listening for events. It can be used at different levels:
Optionalemitter: EmitterThe object to stop listening to. If omitted, stops it for all objects.
Optionalevent: string(Requires the emitter) The name of the event to stop listening to. If omitted, stops it
for all events from emitter.
Optionalcallback: Function(Requires the event) The function to be removed from the call list for the given
event.
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).