Skip to main content

Document splitting

General information​

In order to maintain a proper performance, even with big documents up to several megabytes, Xeditor uses some techniques to improve the performance. The key of those is the document splitting, which only renders a part of the document into the view port. You can think of this as of a virtual DOM.

Basically there's a configuration flag documentPartSize which will determine the size of the visible / rendered part of the document. Xeditor will always keep the entire document stored in the document class, and the currently visible part will be added to the frame class basically being the view port. When the user scrolls for example to the bottom of the currently visible document part (within the frame / view port), the upper part of the visible part will be removed and additional content will be added to the bottom part. Also, Xeditor will ensure that both, the document node and the frame node are kept in sync. This approach guarantees that:

  • the complete document is always maintained without any content loss
  • since the complete document is stored on the client, this even works without an active network connection
  • since only a part of the document is rendered, the performance is smooth regardless of the document size

Document node vs Frame node​

As already mentioned, the complete document, and hence every element, is stored within the document class of Xeditor and is not visible to the user. The visible content (and elements) that are shown in the view port are part of the frame class of Xeditor. This means, that some elements might be available twice, once in the document and once in the frame.

Xeditor offers a couple of API methods for checking whether given node / element is a frame node or a document node. There's also methods for receiving the corresponding document node for a given frame node and vice versa:

Where to use which​

If you want to manipulate the documents actual XML content (e.g. inserting or deleting elements), document nodes are the ones to go with. Actually, in most cases you are going to work with document nodes. As already mentioned, frame nodes are only used for the representation of the document. For example, an image element might look like this:

<image href="https://example.com/some_iamge.png"/>

However, this doesn't add a preview of the actual image within Xeditor. In order to add this, we would add a frame only node (hence, only available within the actual XML), which adds a preview to it. The HTML representation within the frame would then look like this (roughly, doesn't contain all data attributes Xeditor adds to the HTML):

<div data-type="image" href="https://example.com/some_iamge.png">
  <img data-frameonly="true" contenteditable="false" src="https://example.com/some_iamge.png">
</div>

Frame only nodes​

As you can see in the previous example, there's one data attribute data-frameonly="true". As the name might indicate, this is a node that's only part of the Frame, not of the actual document. Those elements are mostly used for manipulating the look and feel of the part shown to the user, without actually changing the underlying XML of the document. On such nodes it's important to set the data-frameonly attribute to true, since Xeditor handles those differently.