Chapter II. Advanced Integration
Prev | 11. Using VersioTrack | Next

## 11. Using VersioTrack

VersioTrack is a powerful add-on for edit-on Pro which enables you to compare different versions of a document directly within edit-on Pro. It highlights and tracks all changes to the document, and allows you to reject or accept all or individual changes to a document in order to produce a final version of a document.

You will find information on how to compare two documents and reject / accept the changes within the document in this chapter.

### 11.1. Comparing Documents

There are multiple to load two documents in comparison mode. You can use the "Compare Documents" dialog to load the documents you want to compare, or one of the API functions `compareDocuments`, `compareDocumentContents`, `compareDocumentToEditorContent` and `compareDocumentContentToEditorContent`.

`compareDocuments` compares two documents from the specified URI to one another:

    eop.compareDocuments(
        "http://www.myserver.com/doc1.html",
        "http://www.myserver.com/doc2.html"
    );
    eop.pumpEvents();

`compareDocumentContents` compares two documents passed as string to one another:

    strDoc1 = "<p>Some content.</p>";
    strDoc2 = "<p>Some more content.</p>";
    eop.compareDocumentContents(strDoc1, strDoc2);
    eop.pumpEvents();

`compareDocumentToEditorContent` compares a document from the specified URI to the editor content:

    eop.compareDocumentToEditorContent("http://www.myserver.com/doc1.html");
    eop.pumpEvents();

`compareDocumentContentToEditorContent` compares a document passed as string to the editor content:

    strDoc = "<p>Some content.</p>";
    eop.compareDocumentContentToEditorContent(strDoc);
    eop.pumpEvents();

As an alternative to the API functions above, you can use the "Compare Documents" dialog to load the documents to be compared. You can integrate this dialog into your user interface using the action `DIFF`. For details please refer to the chapter User Interface Configuration.

### 11.2. Comparison Mode

Once you have loaded the documents to be compared, edit-on Pro with VersioTrack will enter comparison mode as displayed below:

As you can see in the image above, new insertions are highlighted in green and underlined, while deletions are shown in red color and strike-through. Furthermore, formatting changes are highlighted in blue color and underlined.

Note that deletions are also indicated by a red vertical bar in the left margin of the document.

Now that the editor is in comparison mode, you have some tools at your disposition at your disposition which are not available in normal editing mode. You can accept or reject individual changes or all changes either directly, or using a dialog designed for this purpose. Furthermore you can decide to display the changes made to the original document, the final document, or formatting changes.

To display the original document, click "Show Original Document" in comparison mode. Example:

In the original document view, all insertions made in the new document when compared to the old document are also shown as balloons on the right side of the editor canvas.

To display the final document, click "Show Final Document". Example:

In the final document view, all deletions and formatting changes which were made in the new document in contrast to the old document are also displayed in balloons on the right side of the editor canvas.

To display formatting changes, click "Show Formatting Changes". Example:

In formatting changes view, all formatting changes made in the new document are also displayed in balloons on the right side of the document canvas.

The changes made on the document can also be rendered in a list of changes instead of or in addition to the document itself. For example, clicking the "Diff Pane" button will display a list of changes made in the new document:

As displayed above, if one of the changes in the diff pane is clicked, it is also highlighted in darker color in the document itself. Furthermore, you can accept or reject changes directly from within the diff pane itself.

In addition to the diff pane, you can display all changes list format using the "Diff List" dialog:

As you can see above, the "Diff List" dialog also allows you to reject or accept individual or all changes made to the document.

You can of course also reject and accept changes directly within the document itself:

You can use the `PREVDIFF` and `NEXTDIFF` actions to browse through the changes made in the document.

Finally, once you have accepted and rejected all changes made within the document, you can leave comparison mode by calling the "Compare Documents" dialog again and confirming the changes made to the final document.

### 11.3. Comparison Mode 101

You will find some advice on using some of the comparison mode features and APIs here.

Disabled API Functions. First of all, most JavaScript API functions modifying the content of the editor are disabled in comparison mode. The following API functions are still available in comparison mode, but are subject to a different behaviour from their normal mode of operation:

    setHTMLDataFromURL
    setHTMLData
    clear
    compareDocuments
    compareDocumentContents

`setHTMLDataFromURL` will end comparison mode, then load data from the specfied URI.

`setHTMLData` will end comparison mode, then load data from the specified string.

`clear` will end comparison mode, then clear the editor contents.

`compareDocuments` will end comparison mode, load the documents to compare and enter comparison mode.

`compareDocumentContents` will end comparison mode, load the documents to compare and enter comparison mode.

Comparison Mode Event Handlers. As the behaviour of the editor significantly differs from its normal behaviour when in editing mode, you can use new event handlers to determine when comparison mode is entered or ended.

These event handlers are all set using the method `setEventHandler`. The available events are:

    ONACCEPTINSERTIONFINISHED
    ONREJECTINSERTIONFINISHED
    ONACCEPTDELETIONFINISHED
    ONREJECTDELETIONFINISHED
    ONACCEPTFORMATFINISHED
    ONREJECTFORMATFINISHED
    ONACCEPTALLFINISHED
    ONREJECTALLFINISHED
    ONDIFFFINISHED
    ONCANCELDIFFFINISHED
    ONTRACKCHANGES
    ONACCEPTSELECTEDCHANGESFINISHED
    ONREJECTSELECTEDCHANGESFINISHED

Each of these events will be triggered under specific circumstances. For details please see Event Handlers

You can tie each of these events to a custom JavaScript function. The function will be called every time the event it is tied to is fired. Example:

    function onDiffFinished() {
        data = eop.getHTMLData();
    }

    function onDiffCancelled() {
       eop.compareDocumentContents(doc1, doc2);
    }

    eop.setEventHandler("ONDIFFFINISHED","onDiffFinished");
    eop.setEventHandler("ONDIFFCANCELLED","onDiffCancelled");

In the example above, the function `onDiffFinished` is called every time the user successfully ends comparison mode. Each time comparison mode is cancelled, the function `onCancelDiffFinished` is called.

### 11.4. Ignoring Changes

You can configure VersioTrack to ignore certain types of changes when in comparison mode. To do so, you have to set up an ignore filter.

The filter is defined in using XSLT and can be set using the JavaScript API method `setIgnoreFilter`. Here is a sample ignore filter:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:xhtml="http://www.w3.org/1999/xhtml">

        <xsl:template match="/">
         <xsl:copy>
          <xsl:apply-templates select="@*"/>
          <xsl:apply-templates/>
         </xsl:copy>
        </xsl:template>

        <xsl:template match="@*|node()">
         <xsl:copy>
          <xsl:apply-templates select="@*"/>
          <xsl:apply-templates/>
         </xsl:copy>
        </xsl:template>

        <!-- sets the ignored element-->
        <xsl:template match="xhtml:p|xhtml:table">
           <xsl:copy>
                <xsl:attribute name="ignore-element">true</xsl:attribute>
                <xsl:apply-templates select="@*"/>
                <xsl:apply-templates/>
           </xsl:copy>
        </xsl:template>

    </xsl:stylesheet>

For more information, please see http://deltaxml.com/library/how-to-ignore-elements.html

To set the filter we just defined as string, use `setIgnoreFilter`:

    var filter = ... // The filter definition as XSLT expression,see above.
    eop.setIgnoreFilter(filter);
    eop.pumpEvents();

You can also load an ignore filter as file using a setting within the configuration file:

    <diff>
        <ignorefilterurl>http://www.myserver.com/ignorefilter.xsl</ignorefilterurl>
    </diff>

Prev | Up | Next
10. Creating Custom Dialogs | Home | 12. Event Handlers