com.aspose.words

com.aspose.words

Class NodeImporter

  • java.lang.Object
    • com.aspose.words.NodeImporter
public class NodeImporter 
extends java.lang.Object

Allows to efficiently perform repeated import of nodes from one document to another.

Aspose.Words provides functionality for easy copying and moving fragments between Microsoft Word documents. This is known as "importing nodes". Before you can insert a fragment from one document into another, you need to "import" it. Importing creates a deep clone of the original node, ready to be inserted into the destination document.

The simplest way to import a node is to use the DocumentBase.importNode(com.aspose.words.Node,boolean) method provided by the DocumentBase object.

However, when you need to import nodes from one document to another multiple times, it is better to use the NodeImporter class. The NodeImporter class allows to minimize the number of styles and lists created in the destination document.

Copying or moving fragments from one Microsoft Word document to another presents a number of technical challenges for Aspose.Words. In a Word document, styles and list formatting are stored centrally, separately from the text of the document. The paragraphs and runs of text merely reference the styles by internal unique identifiers.

The challenges arise from the fact that styles and lists are different in different documents. For example, to copy a paragraph formatted with the Heading 1 style from one document to another, a number of things must be taken into account: decide whether to copy the Heading 1 style from the source document to the destination document, clone the paragraph, update the cloned paragraph so it refers to the correct Heading 1 style in the destination document. If the style had to be copied, all the styles that it references (based on style and next paragraph style) should be analyzed and possibly copied too and so on. Similar issues exist when copying bulleted or numbered paragraphs because Microsoft Word stores list definitions separately from text.

The NodeImporter class is like a context, that holds the "translation tables" during the import. It correctly translates between styles and lists in the source and destination documents.

Example:

Shows how to insert the contents of one document to a bookmark in another document.
@Test
public void insertAtBookmark() throws Exception {
    Document mainDoc = new Document(getMyDir() + "Document insertion destination.docx");
    Document docToInsert = new Document(getMyDir() + "Document.docx");

    Bookmark bookmark = mainDoc.getRange().getBookmarks().get("insertionPlace");
    insertDocument(bookmark.getBookmarkStart().getParentNode(), docToInsert);

    mainDoc.save(getArtifactsDir() + "NodeImporter.InsertAtBookmark.docx");
}

/// <summary>
/// Inserts content of the external document after the specified node.
/// </summary>
static void insertDocument(Node insertionDestination, Document docToInsert) {
    // Make sure that the node is either a paragraph or table
    if (((insertionDestination.getNodeType()) == (NodeType.PARAGRAPH)) || ((insertionDestination.getNodeType()) == (NodeType.TABLE))) {
        // We will be inserting into the parent of the destination paragraph
        CompositeNode dstStory = insertionDestination.getParentNode();

        // This object will be translating styles and lists during the import
        NodeImporter importer =
                new NodeImporter(docToInsert, insertionDestination.getDocument(), ImportFormatMode.KEEP_SOURCE_FORMATTING);

        // Loop through all block level nodes in the body of the section
        for (Section srcSection : docToInsert.getSections())
            for (Node srcNode : srcSection.getBody()) {
                // Let's skip the node if it is a last empty paragraph in a section
                if (((srcNode.getNodeType()) == (NodeType.PARAGRAPH))) {
                    Paragraph para = (Paragraph) srcNode;
                    if (para.isEndOfSection() && !para.hasChildNodes())
                        continue;
                }

                // This creates a clone of the node, suitable for insertion into the destination document
                Node newNode = importer.importNode(srcNode, true);

                // Insert new node after the reference node
                dstStory.insertAfter(newNode, insertionDestination);
                insertionDestination = newNode;
            }
    } else {
        throw new IllegalArgumentException("The destination node should be either a paragraph or table.");
    }
}
See Also:
Document, DocumentBase.importNode(com.aspose.words.Node,boolean)

Constructor Summary
NodeImporter(DocumentBase srcDoc, DocumentBase dstDoc, intimportFormatMode)
Initializes a new instance of the NodeImporter class.
NodeImporter(DocumentBase srcDoc, DocumentBase dstDoc, intimportFormatMode, ImportFormatOptions importFormatOptions)
Initializes a new instance of the NodeImporter class.
 
Method Summary
NodeimportNode(Node srcNode, boolean isImportChildren)

Imports a node from one document into another.
 

    • Constructor Detail

      • NodeImporter

        public NodeImporter(DocumentBase srcDoc, DocumentBase dstDoc, int importFormatMode)
        Initializes a new instance of the NodeImporter class.
        Parameters:
        srcDoc - The source document.
        dstDoc - The destination document that will be the owner of imported nodes.
        importFormatMode - A ImportFormatMode value. Specifies how to merge style formatting that clashes.

        Example:

        Shows how to insert the contents of one document to a bookmark in another document.
        @Test
public void insertAtBookmark() throws Exception {
    Document mainDoc = new Document(getMyDir() + "Document insertion destination.docx");
    Document docToInsert = new Document(getMyDir() + "Document.docx");

    Bookmark bookmark = mainDoc.getRange().getBookmarks().get("insertionPlace");
    insertDocument(bookmark.getBookmarkStart().getParentNode(), docToInsert);

    mainDoc.save(getArtifactsDir() + "NodeImporter.InsertAtBookmark.docx");
}

/// <summary>
/// Inserts content of the external document after the specified node.
/// </summary>
static void insertDocument(Node insertionDestination, Document docToInsert) {
    // Make sure that the node is either a paragraph or table
    if (((insertionDestination.getNodeType()) == (NodeType.PARAGRAPH)) || ((insertionDestination.getNodeType()) == (NodeType.TABLE))) {
        // We will be inserting into the parent of the destination paragraph
        CompositeNode dstStory = insertionDestination.getParentNode();

        // This object will be translating styles and lists during the import
        NodeImporter importer =
                new NodeImporter(docToInsert, insertionDestination.getDocument(), ImportFormatMode.KEEP_SOURCE_FORMATTING);

        // Loop through all block level nodes in the body of the section
        for (Section srcSection : docToInsert.getSections())
            for (Node srcNode : srcSection.getBody()) {
                // Let's skip the node if it is a last empty paragraph in a section
                if (((srcNode.getNodeType()) == (NodeType.PARAGRAPH))) {
                    Paragraph para = (Paragraph) srcNode;
                    if (para.isEndOfSection() && !para.hasChildNodes())
                        continue;
                }

                // This creates a clone of the node, suitable for insertion into the destination document
                Node newNode = importer.importNode(srcNode, true);

                // Insert new node after the reference node
                dstStory.insertAfter(newNode, insertionDestination);
                insertionDestination = newNode;
            }
    } else {
        throw new IllegalArgumentException("The destination node should be either a paragraph or table.");
    }
}

      • NodeImporter

        public NodeImporter(DocumentBase srcDoc, DocumentBase dstDoc, int importFormatMode, ImportFormatOptions importFormatOptions)
        Initializes a new instance of the NodeImporter class.
        Parameters:
        srcDoc - The source document.
        dstDoc - The destination document that will be the owner of imported nodes.
        importFormatMode - A ImportFormatMode value. Specifies how to merge style formatting that clashes.
        importFormatOptions - Specifies various options to format imported node.

        Example:

        Shows how the numbering will be imported when it clashes in source and destination documents.
        // Open a document with a custom list numbering scheme and clone it
// Since both have the same numbering format, the formats will clash if we import one document into the other
Document srcDoc = new Document(getMyDir() + "Custom list numbering.docx");
Document dstDoc = srcDoc.deepClone();

// Both documents have the same numbering in their lists, but if we set this flag to false and then import one document into the other
// the numbering of the imported source document will continue from where it ends in the destination document
ImportFormatOptions importFormatOptions = new ImportFormatOptions();
importFormatOptions.setKeepSourceNumbering(false);

NodeImporter importer = new NodeImporter(srcDoc, dstDoc, ImportFormatMode.KEEP_DIFFERENT_STYLES, importFormatOptions);
for (Paragraph paragraph : (Iterable<Paragraph>) srcDoc.getFirstSection().getBody().getParagraphs())
{
    Node importedNode = importer.importNode(paragraph, true);
    dstDoc.getFirstSection().getBody().appendChild(importedNode);
}

dstDoc.updateListLabels();
dstDoc.save(getArtifactsDir() + "NodeImporter.KeepSourceNumbering.docx");

    • Method Detail

      • importNode

        public Node importNode(Node srcNode, boolean isImportChildren)

        Imports a node from one document into another.

        Importing a node creates a copy of the source node belonging to the importing document. The returned node has no parent. The source node is not altered or removed from the original document.

        Before a node from another document can be inserted into this document, it must be imported. During import, document-specific properties such as references to styles and lists are translated from the original to the importing document. After the node was imported, it can be inserted into the appropriate place in the document using CompositeNode.insertBefore(com.aspose.words.Node,com.aspose.words.Node) or CompositeNode.insertAfter(com.aspose.words.Node,com.aspose.words.Node).

        If the source node already belongs to the destination document, then simply a deep clone of the source node is created.

        Parameters:
        srcNode - The node to import.
        isImportChildren - True to import all child nodes recursively; otherwise, false.
        Returns:
        The cloned, imported node. The node belongs to the destination document, but has no parent.

        Example:

        Shows how to insert the contents of one document to a bookmark in another document.
        @Test
public void insertAtBookmark() throws Exception {
    Document mainDoc = new Document(getMyDir() + "Document insertion destination.docx");
    Document docToInsert = new Document(getMyDir() + "Document.docx");

    Bookmark bookmark = mainDoc.getRange().getBookmarks().get("insertionPlace");
    insertDocument(bookmark.getBookmarkStart().getParentNode(), docToInsert);

    mainDoc.save(getArtifactsDir() + "NodeImporter.InsertAtBookmark.docx");
}

/// <summary>
/// Inserts content of the external document after the specified node.
/// </summary>
static void insertDocument(Node insertionDestination, Document docToInsert) {
    // Make sure that the node is either a paragraph or table
    if (((insertionDestination.getNodeType()) == (NodeType.PARAGRAPH)) || ((insertionDestination.getNodeType()) == (NodeType.TABLE))) {
        // We will be inserting into the parent of the destination paragraph
        CompositeNode dstStory = insertionDestination.getParentNode();

        // This object will be translating styles and lists during the import
        NodeImporter importer =
                new NodeImporter(docToInsert, insertionDestination.getDocument(), ImportFormatMode.KEEP_SOURCE_FORMATTING);

        // Loop through all block level nodes in the body of the section
        for (Section srcSection : docToInsert.getSections())
            for (Node srcNode : srcSection.getBody()) {
                // Let's skip the node if it is a last empty paragraph in a section
                if (((srcNode.getNodeType()) == (NodeType.PARAGRAPH))) {
                    Paragraph para = (Paragraph) srcNode;
                    if (para.isEndOfSection() && !para.hasChildNodes())
                        continue;
                }

                // This creates a clone of the node, suitable for insertion into the destination document
                Node newNode = importer.importNode(srcNode, true);

                // Insert new node after the reference node
                dstStory.insertAfter(newNode, insertionDestination);
                insertionDestination = newNode;
            }
    } else {
        throw new IllegalArgumentException("The destination node should be either a paragraph or table.");
    }
}