Tipos de operação Mail Merge

A ideia principal de Mail Merge é criar automaticamente um documento ou vários documentos com base no seu modelo e nos dados obtidos da sua fonte de dados. Aspose.Words permite executar dois tipos diferentes de operações Mail Merge: simples Mail Merge e Mail Merge com regiões.

O exemplo mais comum de Utilização do simple Mail Merge é quando pretende enviar um documento para clientes diferentes, incluindo os seus nomes no início do documento. Para fazer isso, você precisa criar campos de mesclagem como First Name e Last Name em seu modelo e, em seguida, preenchê-los com dados de sua fonte de dados. Considerando que o exemplo mais comum de usar Mail Merge com regiões é quando você deseja enviar um documento que inclui pedidos específicos com a lista de todos os itens dentro de cada pedido. Para fazer isso, você precisará criar regiões de mesclagem dentro do seu modelo – região própria para cada pedido, a fim de preenchê-lo com todos os dados necessários para os itens.

A principal diferença entre as duas operações de mesclagem é que simples Mail Merge (sem regiões) repete todo o documento por cada registro da fonte de dados, enquanto Mail Merge com regiões repete apenas regiões designadas por registro. Você pode pensar em uma operação simples Mail Merge como um caso particular de mesclagem com regiões onde a única região é o documento inteiro.

A classe MailMerge representa uma funcionalidade Mail Merge. Com suas propriedades, Você pode personalizar o comportamento necessário antes de executar uma operação Mail Merge.

Operação Simples Mail Merge

Um simples Mail Merge é usado para preencher os campos Mail Merge dentro do seu modelo com os dados necessários da sua fonte de dados (representação de tabela única). Portanto, é semelhante ao clássico Mail Merge em Microsoft Word.

Você pode adicionar um ou mais campos de mesclagem em seu modelo e, em seguida, executar a operação simples Mail Merge. Recomenda-se usá-lo se o seu modelo não contiver regiões de mesclagem.

A principal limitação da utilização deste tipo é que todo o conteúdo do documento será repetido para cada registo na fonte de dados.

Como executar uma operação simples Mail Merge

Assim que o modelo estiver pronto, pode começar a executar a operação simples Mail Merge. Aspose.Words permite executar uma operação simples Mail Merge usando diferentes Executar métodos que aceitam vários objetos de dados como fonte de dados.

O exemplo de código a seguir mostra como executar uma operação Mail Merge simples usando um dos métodos 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");

Você pode notar a diferença entre o documento antes de executar simples mail merge:

E depois de executar simples mail merge:

Como criar vários documentos mesclados

Em Aspose.Words, a operação padrão Mail Merge preenche apenas um único documento com conteúdo da sua fonte de dados. Portanto, você precisará executar a operação Mail Merge várias vezes para criar vários documentos mesclados como saída.

O exemplo de código a seguir mostra como gerar vários documentos mesclados durante uma operação 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);
    }
}

Você pode baixar o arquivo de exemplo deste exemplo em Aspose.Words GitHub.

Mail Merge com regiões

Você pode criar diferentes regiões em seu modelo para ter áreas especiais que você pode simplesmente preencher com seus dados. Use Mail Merge com regiões se quiser inserir tabelas, linhas com dados repetidos para fazer seus documentos crescerem dinamicamente, especificando essas regiões em seu modelo.

Você pode criar regiões aninhadas (filho), bem como mesclar regiões. A principal vantagem de usar este tipo é aumentar dinamicamente as partes dentro de um documento. Veja mais detalhes no próximo artigo"aninhado Mail Merge com regiões".

Informações sobre uma Região Mail Merge podem ser obtidas usando a classe MailMergeRegionInfo.

Como executar Mail Merge com regiões

Uma Região Mail Merge é uma parte específica dentro de um documento que tem um ponto inicial e um ponto final. Ambos os pontos são representados como Mail Merge campos com nomes específicos “TableStart:XXX” e “TableEnd:XXX”. Todo o conteúdo incluído numa região Mail Merge será automaticamente repetido para cada registo na fonte de dados.

Aspose.Words permite executar Mail Merge com regiões usando diferentes Executar métodos que aceitam vários objetos de dados como fonte de dados.

Como primeiro passo, precisamos criar o DataSet para passá-lo posteriormente como um parâmetro de entrada para o método 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;
}

O exemplo de código a seguir mostra como executar Mail Merge com regiões usando o método 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");

Você pode notar a diferença entre o documento antes de executar Mail Merge com regiões:

E depois de executar Mail Merge com regiões:

Limitações de Mail Merge com regiões

Existem alguns pontos importantes que você precisa considerar ao executar um Mail Merge com regiões:

• O ponto inicial TableStart:Orders e o ponto final TableEnd:Orders precisam estar na mesma linha ou célula. Por exemplo, se você iniciar uma região de mesclagem em uma célula de uma tabela, deverá encerrar a região de mesclagem na mesma linha da primeira célula.
• O nome do campo de mesclagem deve corresponder ao nome da coluna em seu DataTable. A menos que você tenha especificado campos mapeados, o Mail Merge com regiões não será bem-sucedido para qualquer campo de mesclagem que tenha um nome diferente do nome da coluna.

Se uma destas regras for violada, obterá resultados inesperados ou poderá ser lançada uma excepção.

Se você não usar Mail Merge regiões, então será semelhante ao Microsoft Word mail merge, e todo o conteúdo do documento será repetido para cada registro na fonte de dados.