Types d'opération Mail Merge

L’idée principale de Mail Merge est de créer automatiquement un document ou plusieurs documents en fonction de votre modèle et des données extraites de votre source de données. Aspose.Words vous permet d’effectuer deux types différents d’opérations Mail Merge: simples Mail Merge et Mail Merge avec des régions.

L’exemple le plus courant d’utilisation de simple Mail Merge est lorsque vous souhaitez envoyer un document à différents clients en incluant leurs noms au début du document. Pour ce faire, vous devez créer des champs de fusion tels que First Name et Last Name dans votre modèle, puis les remplir avec des données de votre source de données. Alors que l’exemple le plus courant d’utilisation de Mail Merge avec des régions est lorsque vous souhaitez envoyer un document qui inclut des commandes spécifiques avec la liste de tous les éléments de chaque commande. Pour ce faire, vous devrez créer des régions de fusion dans votre propre région de modèle pour chaque commande, afin de la remplir avec toutes les données requises pour les articles.

La principale différence entre les deux opérations de fusion est que la simple Mail Merge (sans régions) répète l’intégralité du document pour chaque enregistrement de source de données, tandis que Mail Merge avec des régions répète uniquement les régions désignées par enregistrement. Vous pouvez considérer une simple opération Mail Merge comme un cas particulier de fusion avec des régions où la seule région est le document entier.

La classe MailMerge représente une fonctionnalité Mail Merge. Avec ses propriétés, vous pouvez personnaliser le comportement requis avant d’exécuter une opération Mail Merge.

Opération simple Mail Merge

Un simple Mail Merge est utilisé pour remplir les champs Mail Merge à l’intérieur de votre modèle avec les données requises de votre source de données (représentation de table unique). C’est donc similaire au classique Mail Merge dans Microsoft Word.

Vous pouvez ajouter un ou plusieurs champs de fusion dans votre modèle, puis exécuter l’opération simple Mail Merge. Il est recommandé de l’utiliser si votre modèle ne contient aucune région de fusion.

La principale limitation de l’utilisation de ce type est que l’ensemble du contenu du document sera répété pour chaque enregistrement de la source de données.

Comment exécuter une opération simple Mail Merge

Une fois que votre modèle est prêt, vous pouvez commencer à effectuer l’opération simple Mail Merge. Aspose.Words vous permet d’exécuter une opération Mail Merge simple en utilisant différents Exécuter des méthodes qui acceptent divers objets de données comme source de données.

L’exemple de code suivant montre comment exécuter une opération Mail Merge simple en utilisant l’une des méthodes 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");

Vous pouvez remarquer la différence entre le document avant d’exécuter simple mail merge:

Et après avoir exécuté le simple mail merge:

Comment Créer Plusieurs Documents Fusionnés

Dans Aspose.Words, l’opération standard Mail Merge ne remplit qu’un seul document avec le contenu de votre source de données. Ainsi, vous devrez exécuter l’opération Mail Merge plusieurs fois pour créer plusieurs documents fusionnés en sortie.

L’exemple de code suivant montre comment générer plusieurs documents fusionnés lors d’une opération 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);
    }
}

Vous pouvez télécharger le fichier d’exemple de cet exemple à partir de Aspose.Words GitHub.

Mail Merge avec les régions

Vous pouvez créer différentes régions dans votre modèle pour avoir des zones spéciales que vous pouvez simplement remplir avec vos données. Utilisez le Mail Merge avec des régions si vous souhaitez insérer des tableaux, des lignes avec des données répétitives pour faire croître dynamiquement vos documents en spécifiant ces régions dans votre modèle.

Vous pouvez créer des régions imbriquées (enfants) ainsi que fusionner des régions. Le principal avantage de l’utilisation de ce type est d’augmenter dynamiquement les parties à l’intérieur d’un document. Voir plus de détails dans le prochain article “Imbriqué Mail Merge avec des régions”.

Des informations sur une région Mail Merge peuvent être obtenues en utilisant la classe MailMergeRegionInfo.

Comment exécuter Mail Merge avec des régions

Une région Mail Merge est une partie spécifique d’un document qui a un point de départ et un point final. Les deux points sont représentés par des champs Mail Merge portant des noms spécifiques “TableStart:XXX” et “TableEnd:XXX”. Tout le contenu inclus dans une région Mail Merge sera automatiquement répété pour chaque enregistrement de la source de données.

Aspose.Words vous permet d’exécuter Mail Merge avec des régions utilisant différentes Exécuter des méthodes qui acceptent divers objets de données comme source de données.

Dans un premier temps, nous devons créer le DataSet pour le transmettre plus tard en tant que paramètre d’entrée à la méthode 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;
}

L’exemple de code suivant montre comment exécuter Mail Merge avec des régions à l’aide de la méthode 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");

Vous pouvez remarquer la différence entre le document avant d’exécuter Mail Merge avec des régions:

Et après avoir exécuté Mail Merge avec des régions:

Limitations de Mail Merge avec les régions

Il y a quelques points importants que vous devez prendre en compte lorsque vous effectuez un Mail Merge avec des régions:

• Le point de départ TableStart:Orders et le point final TableEnd:Orders doivent tous deux se trouver dans la même ligne ou cellule. Par exemple, si vous démarrez une région de fusion dans une cellule d’un tableau, vous devez terminer la région de fusion sur la même ligne que la première cellule.
• Le nom du champ de fusion doit correspondre au nom de la colonne dans votre DataTable. Sauf si vous avez spécifié des champs mappés, le Mail Merge avec des régions ne réussira pas pour tout champ de fusion qui a un nom différent de celui de la colonne.

Si l’une de ces règles est enfreinte, vous obtiendrez des résultats inattendus ou une exception peut être levée.

Si vous n’utilisez pas de régions Mail Merge, elles seront similaires à Microsoft Word mail merge et l’ensemble du contenu du document sera répété pour chaque enregistrement de la source de données.