Tipi di operazione Mail Merge

L’idea principale di Mail Merge è creare automaticamente un documento o più documenti in base al modello e ai dati recuperati dall’origine dati. Aspose.Words consente di eseguire due diversi tipi di operazioni Mail Merge: semplice Mail Merge e Mail Merge con regioni.

L’esempio più comune di utilizzo di simple Mail Merge è quando si desidera inviare un documento per diversi client includendo i loro nomi all’inizio del documento. A tale scopo, è necessario creare campi di unione come First Name e Last Name nel modello e quindi compilarli con i dati dell’origine dati. Mentre l’esempio più comune di utilizzo di Mail Merge con le regioni è quando si desidera inviare un documento che include ordini specifici con l’elenco di tutti gli articoli all’interno di ciascun ordine. Per fare ciò, è necessario creare regioni di unione all’interno della propria regione del modello per ogni ordine, in modo da riempirlo con tutti i dati richiesti per gli elementi.

La differenza principale tra entrambe le operazioni di unione è che semplice Mail Merge (senza regioni) ripete l’intero documento per ogni record di origine dati, mentre Mail Merge con regioni ripete solo le regioni designate per record. Si può pensare a una semplice operazione Mail Merge come un caso particolare di unione con regioni in cui l’unica regione è l’intero documento.

La classe MailMerge rappresenta una funzionalità Mail Merge. Con le sue proprietà, è possibile personalizzare il comportamento richiesto prima di eseguire un’operazione Mail Merge.

SempliceMail MergeOperazione

Un semplice Mail Merge viene utilizzato per riempire i campi Mail Merge all’interno del modello con i dati richiesti dall’origine dati (rappresentazione di tabella singola). Quindi è simile al classico Mail Merge in Microsoft Word.

È possibile aggiungere uno o più campi di unione nel modello e quindi eseguire la semplice operazione Mail Merge. Si consiglia di utilizzarlo se il modello non contiene regioni di unione.

La limitazione principale dell’utilizzo di questo tipo è che l’intero contenuto del documento verrà ripetuto per ogni record nell’origine dati.

Come eseguire una semplice operazione Mail Merge

Una volta che il modello è pronto, è possibile iniziare a eseguire la semplice operazione Mail Merge. Aspose.Words consente di eseguire una semplice operazione Mail Merge utilizzando diversi Esegui metodi che accettano vari oggetti dati come origine dati.

Il seguente esempio di codice mostra come eseguire una semplice operazione Mail Merge utilizzando uno dei metodi 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");

È possibile notare la differenza tra il documento prima di eseguire simple mail merge:

E dopo aver eseguito semplice mail merge:

Come creare più documenti uniti

In Aspose.Words, l’operazione standard Mail Merge riempie solo un singolo documento con il contenuto dell’origine dati. Quindi, sarà necessario eseguire l’operazione Mail Merge più volte per creare più documenti uniti come output.

L’esempio di codice seguente mostra come generare più documenti uniti durante un’operazione 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);
    }
}

È possibile scaricare il file di esempio di questo esempio da Aspose.Words GitHub.

Mail Merge con Regioni

Puoi creare diverse regioni nel tuo modello per avere aree speciali che puoi semplicemente riempire con i tuoi dati. Utilizzare Mail Merge con regioni se si desidera inserire tabelle, righe con dati ripetuti per far crescere dinamicamente i documenti specificando tali regioni all’interno del modello.

È possibile creare regioni nidificate (figlio) e unire le regioni. Il vantaggio principale dell’utilizzo di questo tipo è quello di aumentare dinamicamente le parti all’interno di un documento. Vedere ulteriori dettagli nel prossimo articolo “Annidato Mail Merge con regioni”.

Le informazioni su una regione Mail Merge possono essere ottenute usando la classe MailMergeRegionInfo.

Come eseguire Mail Merge con le regioni

Una regione Mail Merge è una parte specifica all’interno di un documento che ha un punto iniziale e un punto finale. Entrambi i punti sono rappresentati come campi Mail Merge con nomi specifici “TableStart:XXX” e “TableEnd:XXX”. Tutto il contenuto incluso in un’area Mail Merge verrà automaticamente ripetuto per ogni record nell’origine dati.

Aspose.Words consente di eseguire Mail Merge con regioni che utilizzano diversi Esegui metodi che accettano vari oggetti dati come origine dati.

Come primo passo, dobbiamo creare il DataSet per passarlo in seguito come parametro di input al metodo 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;
}

Il seguente esempio di codice mostra come eseguire Mail Merge con le regioni utilizzando il metodo 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");

È possibile notare la differenza tra il documento prima di eseguire Mail Merge con le regioni:

E dopo aver eseguito Mail Merge con le regioni:

Limitazioni di Mail Merge con le regioni

Ci sono alcuni punti importanti che è necessario considerare quando si esegue un Mail Merge con le regioni:

• Il punto iniziale TableStart:Orders e il punto finale TableEnd:Orders devono essere entrambi nella stessa riga o cella. Ad esempio, se si avvia un’area di unione in una cella di una tabella, è necessario terminare l’area di unione nella stessa riga della prima cella.
• Il nome del campo Unione deve corrispondere al nome della colonna in DataTable. A meno che non siano stati specificati campi mappati, Mail Merge con regioni non avrà successo per qualsiasi campo di unione con un nome diverso da quello della colonna.

Se una di queste regole viene infranta, si otterranno risultati imprevisti o potrebbe essere generata un’eccezione.

Se non si utilizzano aree Mail Merge, sarà simile a Microsoft Word mail merge e l’intero contenuto del documento verrà ripetuto per ogni record nell’origine dati.