Tipos de Mail Merge Operación

La idea principal de Mail Merge es crear automáticamente un documento o varios documentos en función de su plantilla y los datos obtenidos de su fuente de datos. Aspose.Words le permite realizar dos tipos diferentes de operaciones Mail Merge: Mail Merge simple y Mail Merge con regiones.

El ejemplo más común de uso de simple Mail Merge es cuando desea enviar un documento para diferentes clientes incluyendo sus nombres al principio del documento. Para hacer esto, debe crear campos de combinación como First Name y Last Name en su plantilla y luego completarlos con datos de su fuente de datos. Mientras que el ejemplo más común de usar Mail Merge con regions es cuando desea enviar un documento que incluya pedidos específicos con la lista de todos los artículos dentro de cada pedido. Para hacer esto, deberá crear regiones de combinación dentro de su propia región de plantilla para cada pedido, a fin de completarlo con todos los datos requeridos para los artículos.

La principal diferencia entre ambas operaciones de combinación es que Mail Merge simple (sin regiones) repite todo el documento por cada registro de origen de datos, mientras que Mail Merge con regiones repite solo las regiones designadas por registro. Puede pensar en una operación simple Mail Merge como un caso particular de fusión con regiones donde la única región es todo el documento.

La clase MailMerge representa una funcionalidad Mail Merge. Con sus propiedades, puede personalizar el comportamiento requerido antes de ejecutar una operación Mail Merge.

Operación simple Mail Merge

Se usa un Mail Merge simple para completar los campos Mail Merge dentro de su plantilla con los datos requeridos de su fuente de datos (representación de una sola tabla). Por lo tanto, es similar al clásico Mail Merge en Microsoft Word.

Puede agregar uno o más campos de combinación en su plantilla y luego ejecutar la operación simple Mail Merge. Se recomienda usarlo si su plantilla no contiene regiones de fusión.

La principal limitación de usar este tipo es que todo el contenido del documento se repetirá para cada registro en la fuente de datos.

Cómo Ejecutar una Operación Simple Mail Merge

Una vez que su plantilla esté lista, puede comenzar a realizar la operación simple Mail Merge. Aspose.Words le permite ejecutar una operación Mail Merge simple utilizando diferentes Métodos de ejecución que aceptan varios objetos de datos como origen de datos.

El siguiente ejemplo de código muestra cómo ejecutar una operación Mail Merge simple utilizando uno de los 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");

Puede notar la diferencia entre el documento antes de ejecutar simple mail merge:

Y después de ejecutar simple mail merge:

Cómo Crear Varios Documentos Combinados

En Aspose.Words, la operación estándar Mail Merge llena solo un documento con contenido de su fuente de datos. Por lo tanto, deberá ejecutar la operación Mail Merge varias veces para crear varios documentos combinados como salida.

El siguiente ejemplo de código muestra cómo generar varios documentos combinados durante una operación 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);
    }
}

Puede descargar el archivo de muestra de este ejemplo desde Aspose.Words GitHub.

Mail Merge con regiones

Puede crear diferentes regiones en su plantilla para tener áreas especiales que simplemente puede completar con sus datos. Use el Mail Merge con regiones si desea insertar tablas, filas con datos repetidos para hacer que sus documentos crezcan dinámicamente especificando esas regiones dentro de su plantilla.

Puede crear regiones anidadas (secundarias), así como fusionar regiones. La principal ventaja de usar este tipo es aumentar dinámicamente las partes dentro de un documento. Consulte más detalles en el siguiente artículo “Anidado Mail Merge con regiones”.

La información sobre una región Mail Merge se puede obtener utilizando la clase MailMergeRegionInfo.

Cómo ejecutar Mail Merge con Regiones

Una región Mail Merge es una parte específica dentro de un documento que tiene un punto inicial y un punto final. Ambos puntos se representan como Mail Merge campos que tienen nombres específicos “TableStart:XXX” y “TableEnd:XXX”. Todo el contenido incluido en una región Mail Merge se repetirá automáticamente para cada registro de la fuente de datos.

Aspose.Words le permite ejecutar Mail Merge con regiones que usan diferentes Métodos de ejecución que aceptan varios objetos de datos como origen de datos.

Como primer paso, necesitamos crear el DataSet para pasarlo más tarde como parámetro de entrada al 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;
}

El siguiente ejemplo de código muestra cómo ejecutar Mail Merge con regiones usando el 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");

Puede notar la diferencia entre el documento antes de ejecutar Mail Merge con regiones:

Y después de ejecutar Mail Merge con regiones:

Limitaciones de Mail Merge con regiones

Hay algunos puntos importantes que debe tener en cuenta al realizar un Mail Merge con regiones:

• El punto inicial TableStart:Orders y el punto final TableEnd:Orders deben estar en la misma fila o celda. Por ejemplo, si inicia una región de combinación en una celda de una tabla, debe finalizar la región de combinación en la misma fila que la primera celda.
• El nombre del campo de combinación debe coincidir con el nombre de la columna en su DataTable. A menos que haya especificado campos asignados, el Mail Merge con regiones no tendrá éxito para ningún campo de combinación que tenga un nombre diferente al nombre de la columna.

Si se rompe una de estas reglas, obtendrá resultados inesperados o se puede lanzar una excepción.

Si no usa Mail Merge regiones, será similar a Microsoft Word mail merge y todo el contenido del documento se repetirá para cada registro en la fuente de datos.