This option is required when importing any node from one document to another. It dictates how formatting is resolved when both documents contain the same style but which use different formatting. As the names suggest, ImportFormatMode.KeepSourceFormatting will retain the original formatting used in the source document while ImportFormatMode.UseDestinationStyles will cause any conflicting styles to use the formatting defined in the destination document.
Microsoft Word also provides this option when copying content from one document to another.
When the source formatting is retained for imported content any conflicting styles are copied to the destination document and given a suffix number to distinguish them in the combined document. For example if both documents contain content styled with the style “Normal” then when appending the document the content formatted in destination document with this style will remain formatted with the “Normal” style whereas the content from the source document will be formatted with a newly made style called “Normal_0” which is a copy of the original style used in the source document. Only styles which are actually used in the source document will be copied over to the destination document.
Example
Shows how to append a document to another document while keeping the original formatting.
[Java]
// Load the documents to join.
Document dstDoc = new Document(gDataDir + "TestFile.Destination.doc");
Document srcDoc = new Document(gDataDir + "TestFile.Source.doc");
// Keep the formatting from the source document when appending it to the destination document.
dstDoc.appendDocument(srcDoc, ImportFormatMode.KEEP_SOURCE_FORMATTING);
// Save the joined document to disk.
dstDoc.save(gDataDir + "TestFile.KeepSourceFormatting Out.docx");
This code results in the output below. The conflicting styles are copied to the document and are renamed.
Consolidating styles is handled this way when joining documents as styles that have identical names and identical properties should still remain distinguishable. For example, two documents may be combined which have no relation in any way to each other but which contain two styles names and properties which happen to exactly match by accident. The correct behavior would be for these two styles to remain separate in the combined document so they can both be changed independently which is not possible if they were to be combined into one style.
If you require an option to combine identical styles in order to reduce the number of copied styles, then feel free to post your request on the subject in our forum.
Using destination styles dictates that matching styles in the source document will take on the formatting of the destination document. A block of text in the source document with the style “Heading 1” will remain with that style setting when it’s appended but it will take on the formatting of that style defined n the destination document, even if the “Heading 1” styling is vastly different in the destination document from what it originally was in the source document.
Example
Shows how to append a document to another document using the formatting of the destination document.
[Java]
// Load the documents to join.
Document dstDoc = new Document(gDataDir + "TestFile.Destination.doc");
Document srcDoc = new Document(gDataDir + "TestFile.Source.doc");
// Append the source document using the styles of the destination document.
dstDoc.appendDocument(srcDoc, ImportFormatMode.USE_DESTINATION_STYLES);
// Save the joined document to disk.
dstDoc.save(gDataDir + "TestFile.UseDestinationStyles Out.doc");
Using destination styles has its advantages as it reduces duplicated styles which would occur when using the ImportFormatMode.KeepSourceFormatting option.
This time the appended content uses the destination styles. No extra styles are created in the complete document.
Further information about the different import modes can be found in the API description for the ImportFormatMode enumeration.