Arten von Mail Merge-Operationen

Die Hauptidee von Mail Merge besteht darin, automatisch ein Dokument oder mehrere Dokumente basierend auf Ihrer Vorlage und den aus Ihrer Datenquelle abgerufenen Daten zu erstellen. Mit Aspose.Words können Sie zwei verschiedene Arten von Mail Merge-Operationen ausführen: einfache Mail Merge und Mail Merge mit Regionen.

Das häufigste Beispiel für die Verwendung von einfachem Mail Merge ist, wenn Sie ein Dokument für verschiedene Kunden senden möchten, indem Sie deren Namen am Anfang des Dokuments einfügen. Dazu müssen Sie Seriendruckfelder wie First Name und Last Name in Ihrer Vorlage erstellen und diese dann mit Daten aus Ihrer Datenquelle ausfüllen. Das häufigste Beispiel für die Verwendung von Mail Merge mit Regionen ist, wenn Sie ein Dokument senden möchten, das bestimmte Bestellungen mit der Liste aller Artikel in jeder Bestellung enthält. Dazu müssen Sie für jede Bestellung Zusammenführungsregionen in Ihrer vorlageneigenen Region erstellen, um sie mit allen erforderlichen Daten für die Artikel zu füllen.

Der Hauptunterschied zwischen beiden Zusammenführungsvorgängen besteht darin, dass einfach Mail Merge (ohne Regionen) das gesamte Dokument für jeden Datenquellendatensatz wiederholt, während Mail Merge mit Regionen nur bestimmte Regionen pro Datensatz wiederholt. Sie können sich eine einfache Mail Merge -Operation als einen bestimmten Fall der Zusammenführung mit Regionen vorstellen, in denen die einzige Region das gesamte Dokument ist.

Die MailMerge -Klasse repräsentiert eine Mail Merge -Funktionalität. Mit seinen Eigenschaften können Sie das erforderliche Verhalten anpassen, bevor Sie eine Mail Merge -Operation ausführen.

Einfache Mail Merge Bedienung

Ein einfaches Mail Merge wird verwendet, um die Mail Merge -Felder in Ihrer Vorlage mit den erforderlichen Daten aus Ihrer Datenquelle zu füllen (Einzeltabellendarstellung). Es ähnelt also dem klassischen Mail Merge in Microsoft Word.

Sie können Ihrer Vorlage ein oder mehrere Seriendruckfelder hinzufügen und dann die einfache Operation Mail Merge ausführen. Es wird empfohlen, es zu verwenden, wenn Ihre Vorlage keine Zusammenführungsbereiche enthält.

Die Haupteinschränkung bei der Verwendung dieses Typs besteht darin, dass der gesamte Dokumentinhalt für jeden Datensatz in der Datenquelle wiederholt wird.

So führen Sie eine einfache Mail Merge -Operation {#how-to-execute-a-simple-mail-merge-operation} aus

Sobald Ihre Vorlage fertig ist, können Sie mit der einfachen Operation Mail Merge beginnen. Mit Aspose.Words können Sie eine einfache Mail Merge -Operation mit verschiedenen Methoden ausführen ausführen, die verschiedene Datenobjekte als Datenquelle akzeptieren.

Das folgende Codebeispiel zeigt, wie eine einfache Mail Merge -Operation mit einer der Execute-Methoden ausgeführt wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Include the code for our template.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create Merge Fields.
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

builder.getDocument().save(dataDir + "MailMerge.TestTemplate.docx");

// Fill the fields in the document with user data.
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

builder.getDocument().save(dataDir + "MailMerge.Simple.docx");

Sie können den Unterschied zwischen dem Dokument feststellen, bevor Sie einfach mail merge ausführen:

Und nach dem Ausführen von einfachem mail merge:

So erstellen Sie mehrere zusammengeführte Dokumente

In Aspose.Words füllt der Standardoperation Mail Merge nur ein einzelnes Dokument mit Inhalten aus Ihrer Datenquelle. Sie müssen also die Operation Mail Merge mehrmals ausführen, um mehrere zusammengeführte Dokumente als Ausgabe zu erstellen.

Das folgende Codebeispiel zeigt, wie mehrere zusammengeführte Dokumente während eines Mail Merge-Vorgangs generiert werden:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
public class ProduceMultipleDocumentsDuringMailMerge {

    private static final String dataDir = Utils.getSharedDataDir(ProduceMultipleDocumentsDuringMailMerge.class) + "MailMerge/";

    public static void main(String[] args) throws Exception {

        produceMultipleDocuments(dataDir, "TestFile.doc");
    }

    public static void produceMultipleDocuments(String dataDir, String srcDoc) throws Exception {
        // Open the database connection.
        ResultSet rs = getData(dataDir, "SELECT * FROM Customers");

        // Open the template document.
        Document doc = new Document(dataDir + srcDoc);

        // A record of how many documents that have been generated so far.
        int counter = 1;

        // Loop though all records in the data source.
        while (rs.next()) {
            // Clone the template instead of loading it from disk (for speed).
            Document dstDoc = (Document) doc.deepClone(true);

            // Extract the data from the current row of the ResultSet into a Hashtable.
            Hashtable dataMap = getRowData(rs);

            // Execute mail merge.
            dstDoc.getMailMerge().execute(keySetToArray(dataMap), dataMap.values().toArray());

            // Save the document.
            dstDoc.save(MessageFormat.format(dataDir + "TestFile Out {0}.doc", counter++));
            System.out.println("Counter : ");
        }
    }

    /**
     * Creates a Hashtable from the name and value of each column in the current
     * row of the ResultSet.
     */
    public static Hashtable getRowData(ResultSet rs) throws Exception {
        ResultSetMetaData metaData = rs.getMetaData();
        Hashtable values = new Hashtable();

        for (int i = 1; i <= metaData.getColumnCount(); i++) {
            values.put(metaData.getColumnName(i), rs.getObject(i));
        }

        return values;
    }

    /**
     * Utility function that returns the keys of a Hashtable as an array of
     * Strings.
     */
    public static String[] keySetToArray(Hashtable table) {
        return (String[]) table.keySet().toArray(new String[table.size()]);
    }

    /**
     * Utility function that creates a connection to the Database.
     */
    public static ResultSet getData(String dataDir, String query) throws Exception {

        Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");
        String connectionString = "jdbc:ucanaccess://" + dataDir + "Customers.mdb";

        // DSN-less DB connection.
        Connection connection = DriverManager.getConnection(connectionString);

        Statement statement = connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);

        return statement.executeQuery(query);
    }
}

Sie können die Beispieldatei dieses Beispiels herunterladen von Aspose.Words GitHub.

Mail Merge mit Regionen

Sie können in Ihrer Vorlage verschiedene Regionen erstellen, um spezielle Bereiche zu haben, die Sie einfach mit Ihren Daten füllen können. Verwenden Sie Mail Merge mit Regionen, wenn Sie Tabellen und Zeilen mit sich wiederholenden Daten einfügen möchten, damit Ihre Dokumente dynamisch wachsen, indem Sie diese Regionen in Ihrer Vorlage angeben.

Sie können sowohl verschachtelte (untergeordnete) Regionen erstellen als auch Regionen zusammenführen. Der Hauptvorteil der Verwendung dieses Typs besteht darin, Teile innerhalb eines Dokuments dynamisch zu vergrößern. Weitere Details finden Sie im nächsten Artikel “Verschachtelte Mail Merge mit Regionen”.

Informationen zu einer Mail Merge -Region können mit der MailMergeRegionInfo -Klasse abgerufen werden.

So führen Sie Mail Merge mit Regionen aus

Ein Mail Merge -Bereich ist ein bestimmter Teil in einem Dokument, der einen Start- und einen Endpunkt hat. Beide Punkte werden als Mail Merge -Felder dargestellt, die bestimmte Namen “TableStart:XXX” und “TableEnd:XXX” haben. Alle Inhalte, die in einer Mail Merge-Region enthalten sind, werden automatisch für jeden Datensatz in der Datenquelle wiederholt.

Mit Aspose.Words können Sie Mail Merge mit Regionen ausführen, die verschiedene Methoden ausführen verwenden, die verschiedene Datenobjekte als Datenquelle akzeptieren.

Als ersten Schritt müssen wir die DataSet erstellen, um sie später als Eingabeparameter an die ExecuteWithRegions -Methode zu übergeben:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
private static DataSet CreateDataSet() {
	// Create the customers table.
	DataTable tableCustomers = new DataTable("Customers");
	tableCustomers.getColumns().add("CustomerID");
	tableCustomers.getColumns().add("CustomerName");
	tableCustomers.getRows().add(new Object[] { 1, "John Doe" });
	tableCustomers.getRows().add(new Object[] { 2, "Jane Doe" });

	// Create the orders table.
	DataTable tableOrders = new DataTable("Orders");
	tableOrders.getColumns().add("CustomerID");
	tableOrders.getColumns().add("ItemName");
	tableOrders.getColumns().add("Quantity");
	tableOrders.getRows().add(new Object[] { 1, "Hawaiian", 2 });
	tableOrders.getRows().add(new Object[] { 2, "Pepperoni", 1 });
	tableOrders.getRows().add(new Object[] { 2, "Chicago", 1 });

	// Add both tables to a data set.
	DataSet dataSet = new DataSet();
	dataSet.getTables().add(tableCustomers);
	dataSet.getTables().add(tableOrders);

	// The "CustomerID" column, also the primary key of the customers table is the
	// foreign key for the Orders table.
	dataSet.getRelations().add(tableCustomers.getColumns().get("CustomerID"),
			tableOrders.getColumns().get("CustomerID"));

	return dataSet;
}

Das folgende Codebeispiel zeigt, wie Mail Merge mit Regionen mit der Methode ExecuteWithRegions(DataSet) ausgeführt wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// For complete examples and data files, please go to
// https://github.com/aspose-words/Aspose.Words-for-java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The start point of mail merge with regions the dataset.
builder.insertField(" MERGEFIELD TableStart:Customers");
// Data from rows of the "CustomerName" column of the "Customers" table will go
// in this MERGEFIELD.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// Create column headers
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// We have a second data table called "Orders", which has a many-to-one
// relationship with "Customers"
// picking up rows with the same CustomerID value.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// The end point of mail merge with regions.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// Pass our dataset to perform mail merge with regions.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// Save the result
doc.save(dataDir + "MailMerge.ExecuteWithRegions.docx");

Sie können den Unterschied zwischen dem Dokument feststellen, bevor Sie Mail Merge mit Regionen ausführen:

Und nach dem Ausführen von Mail Merge mit Regionen:

Einschränkungen von Mail Merge mit Regionen

Es gibt einige wichtige Punkte, die Sie beachten müssen, wenn Sie eine Mail Merge mit Regionen durchführen:

• Der Startpunkt TableStart:Orders und der Endpunkt TableEnd:Orders müssen sich beide in derselben Zeile oder Zelle befinden. Wenn Sie beispielsweise einen Zusammenführungsbereich in einer Zelle einer Tabelle beginnen, müssen Sie den Zusammenführungsbereich in derselben Zeile wie die erste Zelle beenden.
• Der Name des Seriendruckfelds muss mit dem Namen der Spalte in Ihrem DataTable übereinstimmen. Sofern Sie keine zugeordneten Felder angegeben haben, ist die Mail Merge mit Regionen für Seriendruckfelder, die einen anderen Namen als den Namen der Spalte haben, nicht erfolgreich.

Wenn eine dieser Regeln verletzt wird, erhalten Sie unerwartete Ergebnisse oder es wird möglicherweise eine Ausnahme ausgelöst.

Wenn Sie keine Mail Merge -Regionen verwenden, ähnelt dies Microsoft Word mail merge, und der gesamte Dokumentinhalt wird für jeden Datensatz in der Datenquelle wiederholt.