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 chaptervar child = editor.document.createElement("chapter");// insert the element before the postNodeelement.insertBefore(child, breakResult.postNode);// fix state because may the insert was not validvar fixResult = element.fixState();// now track everything // start the trackingeditor.document.fireEvent("trackstart", editor, editor.document);// track the breakUntileditor.document.fireTrackingEventsForBreakUntilResult(breakResult);// track the insert of the elementeditor.document.fireEvent("trackelementinsert", editor, editor.document, child);// track the fixState of the elementeditor.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: elementvar parent = element.getParent();// start the trackingeditor.document.fireEvent("trackstart", editor, editor.document);// only remove element if tracking is disabledif(!editor.isTrackingEnabled()){parent.removeChild(element);}// IMPORTANT:// fire trackelementremove before calling fixStateeditor.document.fireEvent('trackelementremove', editor, editor.document, element);// fix state because may the remove is not schema awarevar fixResult = parent.fixState();// track the fixState of the parenteditor.document.fireTrackingEventsForElementFixResult(fixResult);// end the trackingeditor.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 |