Document Model

---

---

⚠⚠ ⚠⚠ ⚠⚠

This wiki served in the early days of CKEditor 5 development and can be severely outdated.

Refer to the official CKEditor 5 documentation for up-to-date information.

---

---

// This documentation is 2 years old and outdated. CKEditor 5 is now is based on a Tree Data Model, still manipulated thought operations, enabling OT. More information about it should be available soon.

CKEditor 5 doesn't use any more a DOM as its main data model. Instead, it introduces a new data model that represents the editable contents. It is generally referenced as the "Document Model" and it has two representations: the Linear Data and the Data Tree.

The Linear Data

The Linear Data is the heart of the Document Model system. It contains the current state of the editor contents, in the form of an array where each item contains the following:

• Data: the entity represented by this entry:
  • Opening Element (analog to <element>)
  • Closing Element (analog to </element>)
  • A single character of text.
• Attributes: Any additional data attached to the entry. This could be configurations of the opening element or styles applied to the character.
• Metadata: Further additional data which is not relevant to the outputted data put participates on the editing experience.

The following is a simplified visualization of this:

// Input HTML:
<h2><em>Sample</em> text</h2>

// Linear Data:
[ 0] <> Root
[ 1] <> "Header" { level: 2 }
[ 2] S { italics: true }
[ 3] a { italics: true }
[ 4] m { italics: true }
[ 5] p { italics: true }
[ 6] l { italics: true }
[ 7] e { italics: true }
[ 8]  
[ 9] t
[10] e
[11] x
[12] t
[13] </> "Header"
[14] </> Root

The Data Tree

The Data Tree derives from the Linear Data as a hierarchical representation of the elements available into it. It enables a fast interaction and manipulation of the tree, which would be extremely complex to do with the Linear Data only.

The following is the simplified visualization of the Data Tree for the example above illustrated in the "The Linear Data" section:

- Root (15)
    - Header (13)
        - Text >> 'Sample text' (11)

Each node in the tree points to a range of indexes (start & end) into the Linear Data, calculated with their lengths (in parentheses). Text nodes represent sequences of characters.

The API

The Document Model API provides features that help manipulate both the Liner Data and the Data Tree. Changes to one model are automatically reflected to the other.

• Liner Data API: based on "Operational Transformation" (see bellow).
• Data Tree API: focused on manipulation of nodes and their hierarchy.

The API entry point is reachable through the editor.dm property.

Operational Tranformation (OT)

One of the key aspects of the proposed Document Model is the possibility of manipulating the document with Operational Transformations (OT). This enables a series of advanced features in CKEditor, like a quality undo stack or even collaborative editing.

In fact, every change that touches the document is reflected internally as OTs, being it done through the Data Tree or through the DOM Document directly (e.g., when typing).

No details about the OT API will be availble in this documentation. We expect the API documentation to bring light about the way it works and how it is used.