انواع عملیات Mail Merge

ایده اصلی Mail Merge این است که به طور خودکار یک سند یا چندین سند بر اساس قالب و داده های شما از منبع داده خود ایجاد کنید. Aspose.Words به شما اجازه می دهد تا دو نوع مختلف از عملیات Mail Merge را انجام دهید: ساده Mail Merge و Mail Merge با مناطق.

رایج ترین مثال استفاده از simple Mail Merge زمانی است که می خواهید یک سند برای مشتریان مختلف با اضافه کردن نام آنها در ابتدای سند ارسال کنید. برای انجام این کار، شما باید زمینه های ادغام مانند First Name و Last Name را در قالب خود ایجاد کنید، و سپس آنها را با داده های منبع داده خود پر کنید. در حالی که رایج ترین مثال استفاده از Mail Merge با مناطق زمانی است که شما می خواهید یک سند ارسال کنید که شامل سفارشات خاص با لیست تمام موارد در هر سفارش است. برای انجام این کار، شما باید مناطق ادغام را در داخل منطقه خود برای هر سفارش ایجاد کنید تا آن را با تمام داده های مورد نیاز برای آیتم ها پر کنید.

تفاوت اصلی بین هر دو عملیات ادغام این است که ساده Mail Merge (بدون مناطق) کل سند را در هر رکورد منبع داده تکرار می کند، در حالی که Mail Merge با مناطق فقط مناطق تعیین شده را در هر رکورد تکرار می کند. شما می توانید یک عملیات ساده Mail Merge را به عنوان یک مورد خاص از ادغام با مناطقی که تنها منطقه کل سند است، در نظر بگیرید.

کلاس MailMerge نشان دهنده یک قابلیت Mail Merge است. با خواص آن، شما می توانید رفتار مورد نیاز را قبل از اجرای یک عملیات Mail Merge سفارشی کنید.

عملیات ساده Mail Merge

یک Mail Merge ساده برای پر کردن فیلدهای Mail Merge داخل قالب شما با داده های مورد نیاز از منبع داده شما (نمایش جدول واحد) استفاده می شود. پس شبیه به کلاسیک Mail Merge در Microsoft Word است.

شما می توانید یک یا چند فیلد ادغام را در قالب خود اضافه کنید و سپس عملیات ساده Mail Merge را اجرا کنید. توصیه می شود از آن استفاده کنید اگر قالب شما شامل هیچ منطقه ادغام نیست.

محدودیت اصلی استفاده از این نوع این است که کل محتوای سند برای هر رکورد در منبع داده تکرار خواهد شد.

چگونه یک عملیات ساده Mail Merge را اجرا کنیم

وقتی قالب شما آماده شد، می توانید عملیات ساده Mail Merge را شروع کنید. Aspose.Words به شما اجازه می دهد تا یک عملیات ساده Mail Merge را با استفاده از روش ها را اجرا کنید مختلف که اشیاء داده های مختلف را به عنوان منبع داده قبول می کند، اجرا کنید.

مثال کد زیر نشان می دهد که چگونه یک عملیات ساده Mail Merge را با استفاده از یکی از روش 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");

شما می توانید تفاوت بین سند را قبل از اجرای ساده متوجه شوید mail merge:

و بعد از اجرای ساده mail merge:

چگونه چندین سند ادغام شده ایجاد کنیم

در Aspose.Words، عملیات استاندارد Mail Merge تنها یک سند را با محتوای منبع داده شما پر می کند. بنابراین، شما باید عملیات Mail Merge را چندین بار اجرا کنید تا چندین سند ادغام شده به عنوان خروجی ایجاد کنید.

مثال کد زیر نشان می دهد که چگونه چندین سند ادغام شده را در طول یک عملیات 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);
    }
}

شما می توانید فایل نمونه این مثال را از Aspose.Words GitHub.

Mail Merge با مناطق

شما می توانید مناطق مختلف را در قالب خود ایجاد کنید تا مناطق خاصی داشته باشید که می توانید به سادگی با داده های خود پر کنید. اگر می خواهید جدول ها، ردیف هایی با داده های تکراری را وارد کنید، از Mail Merge با مناطق استفاده کنید تا اسناد خود را با مشخص کردن آن مناطق در قالب خود به طور پویا رشد دهید.

شما می توانید مناطق آشیانه ای (کودک) و همچنین مناطق ادغام ایجاد کنید. مزیت اصلی استفاده از این نوع افزایش پویا قطعات داخل یک سند است. جزئیات بیشتر را در مقاله بعدی “Nested Mail Merge with Regions"مشاهده کنید.

اطلاعات مربوط به یک منطقه Mail Merge را می توان با استفاده از کلاس MailMergeRegionInfo بدست آورد.

نحوه اجرای Mail Merge با مناطق

منطقه Mail Merge یک بخش خاص در داخل یک سند است که دارای نقطه شروع و نقطه پایان است. هر دو نقطه به عنوان فیلد های Mail Merge که نام های خاص “TableStart:XXX” و “TableEnd:XXX” دارند، نشان داده می شوند. تمام محتوایی که در یک منطقه Mail Merge گنجانده شده است به طور خودکار برای هر رکورد در منبع داده تکرار می شود.

Aspose.Words به شما اجازه می دهد تا Mail Merge را با مناطق با استفاده از روش ها را اجرا کنید مختلف که اشیاء داده های مختلف را به عنوان منبع داده قبول می کنند، اجرا کنید.

به عنوان اولین قدم، ما باید DataSet را ایجاد کنیم تا بعدا آن را به عنوان پارامتر ورودی به روش 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;
}

مثال کد زیر نشان می دهد که چگونه Mail Merge را با مناطق با استفاده از روش 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");

شما می توانید تفاوت بین سند را قبل از اجرای Mail Merge با مناطق مشاهده کنید:

و پس از اجرای Mail Merge با مناطق:

محدودیت های Mail Merge با مناطق

برخی از نکات مهم وجود دارد که شما باید در هنگام انجام یک Mail Merge با مناطق در نظر بگیرید:

• نقطه شروع TableStart:Orders و نقطه پایان TableEnd:Orders هر دو باید در یک ردیف یا سلول باشند. به عنوان مثال، اگر یک منطقه ادغام را در یک سلول جدول شروع کنید، باید منطقه ادغام را در همان ردیف سلول اول پایان دهید.
• نام فیلد ادغام باید با نام ستون در DataTable شما مطابقت داشته باشد. مگر اینکه شما فیلد های نقشه برداری شده را مشخص کرده باشید، Mail Merge با مناطق برای هر فیلد ادغام که نام متفاوتی از نام ستون دارد، موفق نخواهد بود.

اگر یکی از این قوانین شکسته شود، نتایج غیر منتظره ای خواهید داشت یا ممکن است استثنا ایجاد شود.

اگر از مناطق Mail Merge استفاده نکنید، شبیه به Microsoft Word mail merge خواهد بود و کل محتوای سند برای هر رکورد در منبع داده تکرار خواهد شد.