Jenis Operasi Mail Merge

Gagasan utama Mail Merge adalah membuat dokumen atau beberapa dokumen secara otomatis berdasarkan templat Anda dan data yang diambil dari sumber data Anda. Aspose.Words memungkinkan Anda melakukan dua jenis operasi Mail Merge yang berbeda: Mail Merge sederhana dan Mail Merge dengan wilayah.

Contoh paling umum menggunakan Mail Merge sederhana adalah saat Anda ingin mengirim dokumen untuk klien yang berbeda dengan mencantumkan nama mereka di awal dokumen. Untuk melakukannya, Anda perlu membuat bidang gabungan seperti First Name dan Last Name di templat Anda, lalu mengisinya dengan data dari sumber data Anda. Sedangkan contoh paling umum menggunakan Mail Merge dengan wilayah adalah saat Anda ingin mengirim dokumen yang menyertakan pesanan tertentu dengan daftar semua item dalam setiap pesanan. Untuk melakukan ini, Anda perlu membuat wilayah gabungan di dalam wilayah templat Anda sendiri untuk setiap pesanan, untuk mengisinya dengan semua data yang diperlukan untuk item tersebut.

Perbedaan utama antara kedua operasi penggabungan adalah bahwa Mail Merge sederhana (tanpa wilayah) mengulangi seluruh dokumen per setiap catatan sumber data, sedangkan Mail Merge dengan wilayah hanya mengulangi wilayah yang ditentukan per catatan. Anda dapat menganggap operasi Mail Merge sederhana sebagai kasus penggabungan tertentu dengan wilayah di mana satu-satunya wilayah adalah keseluruhan dokumen.

Kelas MailMerge mewakili fungsionalitas Mail Merge. Dengan propertinya, Anda dapat menyesuaikan perilaku yang diperlukan sebelum menjalankan operasi Mail Merge.

Operasi Mail Merge Sederhana

Mail Merge sederhana digunakan untuk mengisi kolom Mail Merge di dalam templat Anda dengan data yang diperlukan dari sumber data Anda (representasi tabel tunggal). Jadi ini mirip dengan Mail Merge klasik di Microsoft Word.

Anda dapat menambahkan satu atau lebih bidang gabungan di templat Anda, lalu menjalankan operasi Mail Merge sederhana. Disarankan untuk menggunakannya jika templat Anda tidak berisi wilayah gabungan apa pun.

Batasan utama penggunaan tipe ini adalah seluruh konten dokumen akan diulang untuk setiap catatan di sumber data.

Cara Menjalankan Operasi Mail Merge Sederhana

Setelah templat Anda siap, Anda dapat mulai melakukan operasi Mail Merge sederhana. Aspose.Words memungkinkan Anda menjalankan operasi Mail Merge sederhana menggunakan Jalankan metode berbeda yang menerima berbagai objek data sebagai sumber data.

Contoh kode berikut menunjukkan cara menjalankan operasi Mail Merge sederhana menggunakan salah satu metode 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");

Anda dapat melihat perbedaan antara dokumen sebelum menjalankan mail mergesederhana:

Dan setelah mengeksekusi mail mergesederhana:

Cara Membuat Beberapa Dokumen Gabungan

Dalam Aspose.Words, operasi Mail Merge standar hanya mengisi satu dokumen dengan konten dari sumber data Anda. Jadi, Anda perlu menjalankan operasi Mail Merge beberapa kali untuk membuat beberapa dokumen gabungan sebagai keluaran.

Contoh kode berikut menunjukkan cara membuat beberapa dokumen gabungan selama operasi 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);
    }
}

Anda dapat mengunduh file contoh contoh ini dari Aspose.Words GitHub.

Mail Merge dengan Wilayah

Anda dapat membuat wilayah berbeda di templat Anda untuk memiliki area khusus yang dapat Anda isi dengan data Anda. Gunakan Mail Merge dengan wilayah jika Anda ingin menyisipkan tabel, baris dengan data berulang untuk membuat dokumen Anda berkembang secara dinamis dengan menentukan wilayah tersebut di dalam templat Anda.

Anda dapat membuat wilayah bersarang (turunan) serta menggabungkan wilayah. Keuntungan utama menggunakan tipe ini adalah menambah bagian di dalam dokumen secara dinamis. Lihat detail selengkapnya di artikel berikutnya “Bersarang Mail Merge dengan Wilayah”.

Informasi tentang wilayah Mail Merge dapat diperoleh dengan menggunakan kelas MailMergeRegionInfo.

Cara Mengeksekusi Mail Merge dengan Region

Wilayah Mail Merge adalah bagian tertentu di dalam dokumen yang memiliki titik awal dan titik akhir. Kedua titik direpresentasikan sebagai bidang Mail Merge yang memiliki nama spesifik “TableStart:XXX” dan “TableEnd:XXX”. Semua konten yang disertakan dalam wilayah Mail Merge akan diulang secara otomatis untuk setiap rekaman di sumber data.

Aspose.Words memungkinkan Anda menjalankan Mail Merge dengan wilayah menggunakan Jalankan metode berbeda yang menerima berbagai objek data sebagai sumber data.

Sebagai langkah pertama, kita perlu membuat DataSet untuk diteruskan nanti sebagai parameter input ke metode 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;
}

Contoh kode berikut menunjukkan cara menjalankan Mail Merge dengan wilayah menggunakan metode 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");

Anda dapat melihat perbedaan antara dokumen sebelum mengeksekusi Mail Merge dengan wilayah:

Dan setelah mengeksekusi Mail Merge dengan wilayah:

Batasan Mail Merge dengan Wilayah

Ada beberapa poin penting yang perlu Anda pertimbangkan saat melakukan Mail Merge dengan wilayah:

• Titik awal TableStart:Orders dan titik akhir TableEnd:Orders keduanya harus berada di baris atau sel yang sama. Misalnya, jika Anda memulai wilayah penggabungan di sel tabel, Anda harus mengakhiri wilayah penggabungan di baris yang sama dengan sel pertama.
• Nama bidang gabungan harus cocok dengan nama kolom di DataTable Anda. Kecuali Anda telah menentukan bidang yang dipetakan, Mail Merge dengan wilayah tidak akan berhasil untuk bidang gabungan apa pun yang memiliki nama berbeda dari nama kolom.

Jika salah satu dari aturan ini dilanggar, Anda akan mendapatkan hasil yang tidak terduga atau pengecualian dapat dilemparkan.

Jika Anda tidak menggunakan wilayah Mail Merge, maka wilayah tersebut akan serupa dengan Microsoft Word mail merge, dan seluruh konten dokumen akan diulang untuk setiap catatan di sumber data.