Skip to main content

Change Tracking

Structured track changes

Xeditor offers an advanced structural change tracking feature that is able to handle changes performed by multiple different users. This allows authors and reviewers to always have full access to performed changes like:

  • Inserted/removed block/inline elements
  • Inserted/removed breaks
  • Cutting/pasting elements
  • Moving whole text blocks to different positions using the Table of Contents Plugin

In addtion, once the change tracking has been activated, it can be only turned off when all changes are accepted. Otherwise, turning off the change tracking would break the document.

How to use it

The track changes functionality uses several events that have to be fired by the code manipulating the document. Therefore, it is in the responsibility of the developer to fire appropriate events for custom code not included with Xeditor. Xeditor’s API will list on each method that manipulates the document whether the tracking events need to be fired manually or if they are already included in the core method.

Event (* = required)Description
trackelementinsertif an element was inserted
trackrangeinsertif a range of elements was inserted
trackelementremoveif an element was removed
trackrangeremoveif a range of elements or text was removed
trackelementmoveif an element was moved
trackelementsplitif an element was split
trackelementwrapif an element was wrapped
trackelementunwrapif an element was unwrapped
trackelementcloneif an element was cloned and should still contain the changes of the previous element
trackstart *indicates the start of the change action
trackend *indicates the end of the change action

Example of insert element with change tracking:

// File: editor_config.js [FILE WITH YOUR CUSTOM CODE]
// Ext.ux.xeditor.Editor: editor
// Ext.ux.xeditor.Element: element

// break at the current position until the element is reached.
var breakResult = editor.document.breakUntil(element);
if (!breakResult) {
return;
}

// create new child of type chapter
var child = editor.document.createElement("chapter");

// insert the element before the postNode
element.insertBefore(child, breakResult.postNode);

// fix state because may the insert was not valid
var fixResult = element.fixState();

// now track everything // start the tracking
editor.document.fireEvent("trackstart", editor, editor.document);

// track the breakUntil
editor.document.fireTrackingEventsForBreakUntilResult(breakResult);

// track the insert of the element
editor.document.fireEvent("trackelementinsert", editor, editor.document, child);

// track the fixState of the element
editor.document.fireTrackingEventsForElementFixResult(fixResult);

// end the tracking editor.document.fireEvent("trackend", editor, editor.document);

Example of remove element with change tracking:

// File: editor_config.js [FILE WITH YOUR CUSTOM CODE]
// Ext.ux.xeditor.Editor: editor
// Ext.ux.xeditor.Element: element

var parent = element.getParent();

// start the tracking
editor.document.fireEvent("trackstart", editor, editor.document);

// only remove element if tracking is disabled
if(!editor.isTrackingEnabled()){
parent.removeChild(element);
}

// IMPORTANT:
// fire trackelementremove before calling fixState
editor.document.fireEvent('trackelementremove', editor, editor.document, element);

// fix state because may the remove is not schema aware
var fixResult = parent.fixState();

// track the fixState of the parent
editor.document.fireTrackingEventsForElementFixResult(fixResult);

// end the tracking
editor.document.fireEvent("trackend", editor, editor.document);

Buttons

This plugin exports the following button templates that can be used in your toolbar configuration:

NameFunction
button:xeditor.changetrackerToggles change tracking
button:xeditor.changetracker.previousSelects previous change
button:xeditor.changetracker.nextSelects next change
button:xeditor.changetracker.commitCommits selected change
button:xeditor.changetracker.revertReverts selected change