أنواع Mail Merge عملية

الفكرة الرئيسية لـ Mail Merge هي إنشاء مستند أو مستندات متعددة تلقائيا بناء على القالب والبيانات التي تم جلبها من مصدر البيانات الخاص بك. Aspose.Words يسمح لك بإجراء نوعين مختلفين من Mail Merge العمليات: بسيطة Mail Merge و Mail Merge مع المناطق.

المثال الأكثر شيوعا لاستخدام بسيط 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 مع المناطق إذا كنت ترغب في إدراج الجداول والصفوف مع تكرار البيانات لجعل المستندات الخاصة بك تنمو بشكل حيوي عن طريق تحديد تلك المناطق داخل القالب.

يمكنك إنشاء مناطق متداخلة (فرعية) بالإضافة إلى مناطق دمج. الميزة الرئيسية لاستخدام هذا النوع هي زيادة الأجزاء داخل المستند ديناميكيا. اطلع على مزيد من التفاصيل في المقالة التالية “متداخلة Mail Merge مع المناطق”.

يمكن الحصول على معلومات حول منطقة 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، وسيتم تكرار محتوى المستند بالكامل لكل سجل في مصدر البيانات.