Folding DiffReport with DCP

 Table of Contents

1. Introduction

1.1. DCP and the Document Comparator

For this sample we will use XML Compare's Document Comparator component. We show how extensions to its built-in processing pipeline can be conveniently accessed using the included Document Comparator Pipeline (DCP) definition file 'diffreport.dcp'.

More information on the Document Comparator and DCP can be found here:

1.2. The Folding DiffReport

XML Compare includes built-in XSLT stylesheets for rendering XML comparison results using HTML to highlight differences at the syntax-level; this sample focuses on the 'folding' view, but there is also a 'side-by-side' view. The 'side-by-side' view is similar to the folding DiffReport but shows two synchronised-scrolling folding XML views

A folding DiffReport shows formatted XML syntax with folding points highlighted with an arrow icon. Clicking on the arrow either folds or unfolds the adjacent XML, depending on its current view state. When the comparison result is first rendered, nodes with fold-points that have changes are shown expanded and all other fold-points are collapsed. Nodes that have changes have start and end tags coloured in blue, unchanged nodes are shown in grey.

A screenshot of the DiffReport as rendered in a browser:

A simple toolbar along with a 'breadcrumb' view of the currently selected change is shown above the folding view in the DiffReport, there is also a 'Differences List' shown as a vertical panel alongside.

2. Using DCP to add an output filter

To render a folding DiffReport, it is necessary to add the included XSLT resource xsl/dx2-deltaxml-folding-html.xsl as the final output filter (this XSLT is also available externally in the samples/xsl-filters directory). The following snippet from the DCP file shows how this is done:

  ...
  <extensionPoints>
    ...
    <outputExtensionPoints>
      <finalPoint>
        <filter if="convert-to-html">
          <resource name="xsl/dx2-deltaxml-folding-html.xsl"/>
          <parameter name="smart-whitespace-normalization" 
             parameterRef="smart-whitespace-normalization"/>
             ...
        </filter>
      </finalPoint>
    </outputExtensionPoints>
  </extensionPoints>    

The code above shows one of the available parameters for the DiffReport XSLT using a parameterRef attribute to associate it with a DCP parameter. (Note: for a 'side-by-side' change the resource name to 'dx2-deltaxml-sbs-folding-html.xsl'). A full description of all the DCP parameters is shown using the command-line. Replace x.y.z with the major.minor.patch version number of your release e.g. command-10.0.0.jar

java -jar ../../command-x.y.z.jar describe dcp-folding

Alternatively, if you're using the .NET distribution of XML Compare, the following command is equivalent:

..\..\bin\deltaxml.exe describe dcp-folding

'dcp-folding' is the configuration id included in the DCP file. The output from running the above command summarises the purpose of this DCP and briefly describes each of the defined DCP parameters, as seen below.

  Pipeline ID: 'dcp-folding'

  Location:
    file:{install-dir}/DeltaXML-XML-Compare-9_0_7_j/samples/DCPdiffReport/diffreport.dcp

  Short Description:
    Render result as folding html view.

  Boolean Parameters:
    Name                 | Default Value | Description                        
    -------------------- | ------------- | -----------------------------------
    convert-to-html      | true          | Show result as folding html        
    load-external-dtd    | false         | Load an external DTD referenced by 
                         |               |   the input XML                    
    indent-xml           | true          | Indent the serialized XML result   
    resolve-formatting-  | true          | For formatting-element changes, use
      diffs              |               |   those found in the 'B' document  

  String Parameters:
    Name              | Default Value            | Description                
    ----------------- | ------------------------ | ---------------------------
    formatting-       | b,i,u,em,strong,emphasis | Comma-separated list of    
      element-list    |                          |   formatting elements      
                      |                          |   defined in the input XML 
                      |                          |   grammar.                 
    schema-location   |                          | Space-separated list: For  
                      |                          |   each supplied namespace  
                      |                          |   give the location of an  
                      |                          |   associated XML Schema    
                      |                          |   file. Schema validation  
                      |                          |   will only be performed   
                      |                          |   when this value is non-  
                      |                          |   empty.                   
    add-all-          | false                    | If true, all namespaces in 
      namespace-      |                          |   rendering are declared   
      declarations    |                          |   in-situ - otherwise, only
                      |                          |   root element namespaces  
                      |                          |   are declared             
    minimize-         | false                    | Collapse and do not embed  
      unchanged-      |                          |   unchanged subtrees in    
      display         |                          |   result - helps minimize  
                      |                          |   file size                
    no-fold-size      | 50                       | Childless nodes of         
                      |                          |   character-length less    
                      |                          |   that this are shown in   
                      |                          |   full - and are not       
                      |                          |   foldable
      

3. Running the sample

The sample code can be downloaded from Bitbucket https://bitbucket.org/deltaxml/folding-diffreport for Java and here for .NET.

Details of how to run the sample are given in the file README.md.

4. What the Sample Does

The sample code performs two comparisons using the Document Comparator. Each uses the same DCP file to configure the comparator, but with the convert-to-html parameter set true in the first comparison and false in the second.

The output files from the two comparisons are result1.html and result2.xml. The latter file is the 'delta' XML output, which is initially harder to understand than the html-rendered DiffReport, but may be useful for reference.

4.1. Notes on DCPConfiguration Java API

The DCPConfiguration class in the samples is used to manage DCP configurations using the API. This class has 'generate' and 'setParams' methods that are used to create or modify a DocumentComparator configured using the DCP file. Any parameter overrides are supplied within Map arguments for these methods. Full source code is included in the DCPConfigurationSample.java source file. A snippet is shown below.

    ...
    Map dcpStringParams= new HashMap<String, String>();
    dcpStringParams.put("formatting-element-list", "b,i,u");
    Map dcpBooleanParams= new HashMap<String, Boolean>();
    dcpBooleanParams.put("convert-to-html", true);
    
    DCPConfiguration dcp= new DCPConfiguration(dcpDefinition);
    
    // generate with initial configuration
    dcp.generate(dcpBooleanParams, dcpStringParams);
    
    DocumentComparator comparator = dcp.getDocumentComparator();   
    File result1= new File(dcResultFolder, "result1.html");
    // comparison 1:
    comparator.compare(input1, input2, result1);
    
    // now modify configuration
    dcpBooleanParams.put("convert-to-html", false);
    dcp.setParams(dcpBooleanParams, dcpStringParams);  
    
    File result2= new File(dcResultFolder, "result2.xml");
    // comparison 2:
    comparator.compare(input1, input2, result2);
    ...
    
#content .code