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
trackelementinsert	if an element was inserted
trackrangeinsert	if a range of elements was inserted
trackelementremove	if an element was removed
trackrangeremove	if a range of elements or text was removed
trackelementmove	if an element was moved
trackelementsplit	if an element was split
trackelementwrap	if an element was wrapped
trackelementunwrap	if an element was unwrapped
trackelementclone	if 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:

Name	Function
button:xeditor.changetracker	Toggles change tracking
button:xeditor.changetracker.previous	Selects previous change
button:xeditor.changetracker.next	Selects next change
button:xeditor.changetracker.commit	Commits selected change
button:xeditor.changetracker.revert	Reverts selected change