Типы операций 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 с регионами, если вы хотите вставлять таблицы, строки с повторяющимися данными, чтобы ваши документы динамически расширялись, указав эти области в вашем шаблоне.

Вы можете создавать вложенные (дочерние) области, а также объединять области. Основное преимущество использования этого типа заключается в динамическом увеличении частей внутри документа. Более подробную информацию смотрите в следующей статье “Вложенные 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, и все содержимое документа будет повторяться для каждой записи в источнике данных.