Typy operací Mail Merge

Hlavní myšlenkou Mail Merge je automatické vytvoření dokumentu nebo více dokumentů na základě vaší šablony a dat načtených ze zdroje dat. Aspose.Words umožňuje provádět dva různé typy operací Mail Merge: Jednoduché Mail Merge a Mail Merge s regiony.

Nejběžnějším příkladem použití jednoduchého Mail Merge je, když chcete odeslat dokument pro různé klienty zahrnutím jejich jmen na začátek dokumentu. Chcete-li to provést, musíte v šabloně vytvořit slučovací pole, například First Name a Last Name, a poté je vyplnit daty ze zdroje dat. Zatímco nejběžnějším příkladem použití Mail Merge s regiony je, když chcete odeslat dokument, který obsahuje konkrétní objednávky se seznamem všech položek v každé objednávce. Chcete – li to provést, budete muset vytvořit slučovací oblasti uvnitř vaší šablony-vlastní oblast pro každou objednávku, abyste ji mohli vyplnit všemi požadovanými údaji pro položky.

Hlavní rozdíl mezi oběma operacemi sloučení spočívá v tom, že jednoduché Mail Merge (bez oblastí) opakuje celý dokument na každý záznam zdroje dat, zatímco Mail Merge s oblastmi opakuje pouze určené oblasti na záznam. Jednoduchou operaci Mail Merge si můžete představit jako konkrétní případ sloučení s regiony, kde jedinou oblastí je celý dokument.

Třída MailMerge představuje funkci Mail Merge. S jeho vlastnostmi můžete přizpůsobit požadované chování před provedením operace Mail Merge.

Jednoduchá Operace Mail Merge

Jednoduchý Mail Merge se používá k vyplnění polí Mail Merge uvnitř šablony požadovanými daty ze zdroje dat (reprezentace jedné tabulky). Je to tedy podobné klasice Mail Merge v Microsoft Word.

Do šablony můžete přidat jedno nebo více polí sloučení a poté provést jednoduchou operaci Mail Merge. Doporučujeme jej použít, pokud vaše šablona neobsahuje žádné slučovací oblasti.

Hlavním omezením použití tohoto typu je, že celý obsah dokumentu se bude opakovat pro každý záznam ve zdroji dat.

Jak provést jednoduchou operaci Mail Merge

Jakmile je vaše šablona připravena, můžete začít provádět jednoduchou operaci Mail Merge. Aspose.Words umožňuje provést jednoduchou operaci Mail Merge pomocí různých Execute methods, které jako zdroj dat přijímají různé datové objekty.

Následující příklad kódu ukazuje, jak provést jednoduchou operaci Mail Merge pomocí jedné z metod Execute:

// 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");

Rozdíl mezi dokumentem si můžete všimnout před provedením jednoduchého mail merge:

A po provedení jednoduchého mail merge:

Jak vytvořit více sloučených dokumentů

V Aspose.Words vyplní standardní operace Mail Merge pouze jeden dokument s obsahem ze zdroje dat. Takže budete muset provést operaci Mail Merge vícekrát, abyste vytvořili více sloučených dokumentů jako výstup.

Následující příklad kódu ukazuje, jak generovat více sloučených dokumentů během operace Mail Merge:

// 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);
    }
}

Ukázkový soubor tohoto příkladu si můžete stáhnout z Aspose.Words GitHub.

Mail Merge s regiony

V šabloně můžete vytvořit různé oblasti, abyste měli speciální oblasti, které můžete jednoduše vyplnit svými daty. Pokud chcete vložit tabulky, řádky s opakujícími se daty, použijte Mail Merge s regiony, aby vaše dokumenty dynamicky rostly zadáním těchto oblastí v šabloně.

Můžete vytvářet vnořené (podřízené) regiony i slučovat regiony. Hlavní výhodou použití tohoto typu je dynamicky zvětšovat části uvnitř dokumentu. Další podrobnosti naleznete v dalším článku “vnořené Mail Merge s regiony”.

Informace o oblasti Mail Merge lze získat pomocí třídy MailMergeRegionInfo.

Jak spustit Mail Merge s regiony

Oblast Mail Merge je specifická část uvnitř dokumentu, která má počáteční a koncový bod. Oba body jsou reprezentovány jako pole Mail Merge, která mají specifické názvy “TableStart:XXX” a “TableEnd:XXX”. Veškerý obsah, který je zahrnut v oblasti Mail Merge, se automaticky opakuje pro každý záznam ve zdroji dat.

Aspose.Words umožňuje spustit Mail Merge s oblastmi pomocí různých Execute methods, které přijímají různé datové objekty jako zdroj dat.

Jako první krok musíme vytvořit DataSet, abychom jej později předali jako vstupní parametr metodě ExecuteWithRegions:

// 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;
}

Následující příklad kódu ukazuje, jak provést Mail Merge s regiony pomocí metody ExecuteWithRegions(DataSet):

// 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");

Rozdíl mezi dokumentem si můžete všimnout před spuštěním Mail Merge s regiony:

A po provedení Mail Merge s regiony:

Omezení Mail Merge s regiony

Při provádění Mail Merge s regiony je třeba vzít v úvahu několik důležitých bodů:

• Počáteční bod TableStart:Orders a koncový bod TableEnd:Orders musí být ve stejném řádku nebo buňce. Pokud například spustíte oblast sloučení v buňce tabulky, musíte oblast sloučení ukončit ve stejném řádku jako první buňka.
• Název sloučeného pole se musí shodovat s názvem sloupce ve vašem DataTable. Pokud jste nezadali mapovaná pole, Mail Merge s oblastmi nebude úspěšné pro žádné slučovací pole, které má jiný název než název sloupce.

Pokud je jedno z těchto pravidel porušeno, získáte neočekávané výsledky nebo může být vyvolána výjimka.

Pokud nepoužíváte oblasti Mail Merge, bude to podobné Microsoft Word mail merge a celý obsah dokumentu se bude opakovat pro každý záznam ve zdroji dat.