Le publipostage est une fonctionnalité de Microsoft Word qui permet de créer rapidement et facilement des documents tels que des lettres, des étiquettes et des enveloppes. Aspose.Words Cloud reprend le publipostage standard et le fait progresser de plusieurs crans, le transformant en une solution de reporting à part entière qui vous permet de générer des documents encore plus complexes tels que des rapports, des catalogues, des inventaires et des factures. Les avantages de la solution de reporting Aspose.Words Cloud sont les suivants :
- Concevoir des rapports dans Microsoft Word à l’aide de champs de publipostage standard
- Définir des régions du document qui se développent, telles que les lignes de détails d’une commande
- Insérer des images lors du publipostage
- Insérer du code HTML lors du publipostage
Étapes de base
Les étapes à suivre pour effectuer un publipostage sont assez simples. Tout d’abord, vous utilisez Microsoft Word pour créer et concevoir un document Word, normalement appelé modèle. Notez que le document n’a pas besoin d’être un modèle Microsoft Word (.dot), il peut s’agir d’un document .doc normal. Vous insérez des champs spéciaux appelés champs de fusion dans le modèle aux endroits où vous souhaitez que les données de votre source de données soient insérées ultérieurement. Ensuite, avec l’API REST Aspose.Words, vous exécutez une opération de publipostage. L’opération de publipostage prendra les données de votre source de données et les fusionnera dans le document.
Vous pouvez également désigner des zones de fusion répétables dans le document ou insérer des champs de fusion spéciaux qui vous permettent d’insérer d’autres contenus tels que des images. Selon la manière dont vous configurez les champs de fusion et les zones répétables dans le document, le document s’agrandira pour accueillir plusieurs enregistrements dans votre source de données. Si vous n’utilisez pas de zones de fusion, le publipostage sera similaire au publipostage de Microsoft Word et l’intégralité du contenu du document sera répétée pour chaque enregistrement de la source de données. En utilisant des zones de fusion répétables, vous pouvez désigner des parties à l’intérieur d’un document qui seront répétées pour chaque enregistrement de la source de données. Par exemple, si vous marquez une ligne de tableau comme une zone répétable, cette ligne de tableau sera répétée, ce qui entraînera la croissance dynamique du tableau pour accueillir toutes vos données.
Préparer un document
Avant d’exécuter un publipostage, vous devez préparer le modèle de document. Vous devez insérer des champs de fusion qui seront remplacés par des valeurs provenant de votre source de données.
Insertion de champs de fusion dans un document
Pour insérer des champs de fusion dans un document :
- Ouvrez votre document dans Microsoft Word.
- Dans le document, cliquez à l’endroit où vous souhaitez placer un champ de fusion.
- Ouvrez le menu Insérer et sélectionnez Champ pour ouvrir la boîte de dialogue Champ.
- Dans la liste Noms de champs, sélectionnez MergeField.
- Dans la zone de texte Nom du champ, entrez un nom pour le champ de fusion et appuyez sur OK.
Étant donné qu’un champ de fusion est un champ Microsoft Word standard, vous pouvez basculer entre l’affichage des codes de champ et des résultats dans votre document Microsoft Word à l’aide du raccourci clavier Alt+F9. Les codes de champ apparaissent entre accolades.
Publipostage simple
Afin de préparer votre modèle pour effectuer un publipostage simple (sans régions, similaire au publipostage classique disponible dans Microsoft Word), vous devez simplement insérer un ou plusieurs champs de fusion aux endroits que vous souhaitez remplir avec les données de la source de données.
Examinons la démonstration d’invitation à un dîner. Elle crée une lettre pour une liste de clients définie dans la source de données. Le modèle contient un certain nombre de champs de fusion qui sont renseignés à partir de deux sources de données ; en d’autres termes, deux opérations de publipostage sont effectuées l’une après l’autre. Tout d’abord, les données de la première source de données sont fusionnées dans le modèle. Cette source de données ne contient qu’une seule ligne, car il s’agit d’informations sur l’invitant. Ainsi, le contenu du document dans son intégralité n’est pas répété et seuls les champs appropriés sont renseignés. Ensuite, la deuxième opération de publipostage est exécutée. La source de données qu’elle utilise contient des informations sur les clients. L’ensemble du modèle est répété pour chaque ligne de données et chaque copie répétée est renseignée avec les données du client correspondant.
Nous disposons ainsi d’un document composé de cinq lettres d’invitation complétées, complètes et personnalisées (un fragment de la toute première est présenté ci-dessous) :
Comme vous pouvez le constater, il est possible, et parfois utile, d’effectuer plusieurs opérations de fusion avec le même modèle pour ajouter des données par étapes. Vous pouvez insérer des champs NEXT dans le document Word pour que le moteur de publipostage sélectionne l’enregistrement suivant dans la source de données et poursuive la fusion. Lorsque le moteur rencontre un champ NEXT, il sélectionne simplement l’enregistrement suivant dans la source de données et continue la fusion sans copier aucun contenu. Cela peut être utilisé lors de la création de documents tels que des étiquettes de publipostage.
Le code pour effectuer un publipostage simple est donné ci-dessous :
// Pour des exemples complets et des fichiers de données, veuillez consulter https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "DinnerInvitation.docx";
var destFileName = "InviterAdded.docx";
var data = File.ReadAllText(@"c:\Data\" + "Inviter.xml");
string folder = null; // File exists at the root of the storage
// Télécharger le document source sur le stockage cloud
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
// Exécuter l'opération de publipostage pour la première fois
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
// Exécuter l'opération de publipostage une deuxième fois
fileName = destFileName;
destFileName = "FinalDinnerInvitation.docx";
data = File.ReadAllText(@"c:\Data\" + "Clients.xml");
executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
Publipostage avec régions
Si vous souhaitez développer dynamiquement des parties à l’intérieur du document, utilisez la fusion et le publipostage avec des régions. Pour spécifier une région de fusion et de publipostage dans le document, vous devez insérer deux champs de fusion et de publipostage pour marquer le début et la fin de la région de fusion et de publipostage. Tout le contenu du document inclus dans une région de fusion et de publipostage sera automatiquement répété pour chaque enregistrement de la source de données.
Pour marquer le début d’une région de publipostage, insérez un MERGEFIELD avec le nom TableStart:MyTable, où MyTable correspond respectivement à la balise ou à la clé dans XML ou JSON. Pour marquer la fin de la région de publipostage, insérez un autre MERGEFIELD avec le nom TableEnd:MyTable. Entre ces champs de marquage, placez des champs de fusion qui correspondent aux champs de votre source de données. Ces champs de fusion seront renseignés avec les données de la première ligne de la source de données, puis toute la région sera répétée, et les nouveaux champs seront renseignés avec les données de la deuxième ligne, et ainsi de suite.
Suivez ces règles simples lorsque vous marquez une région :
- Les champs TableStart et TableEnd doivent se trouver dans la même section du document
- S’ils sont utilisés à l’intérieur d’un tableau, TableStart et TableEnd doivent être à l’intérieur de la même ligne du tableau
- Les régions de publipostage peuvent être imbriquées les unes dans les autres
- Les régions de publipostage doivent être bien formées (il existe toujours une paire de TableStart et TableEnd correspondants avec le même nom de table)
À titre d’exemple, regardez la démonstration du catalogue d’articles. Voici un fragment d’une région préparée pour le publipostage :
Notez que les deux champs de marquage TableStart:Item et TableEnd:Item sont placés dans la même ligne du tableau Word. Après avoir exécuté le publipostage, voici le résultat :
Le code pour effectuer le publipostage avec les régions est donné ci-dessous :
// Pour des exemples complets et des fichiers de données, veuillez consulter https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "Invoice_Template.doc";
var destFileName = "Invoice_Template_out_.doc";
var data = File.ReadAllText(@"c:\Data\" + "CustomerData.xml");
string folder = null; // File exists at the root of the storage
// Télécharger le document d'entrée vers le stockage cloud
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: true);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
Publipostage utilisant la syntaxe du modèle « Moustache »
Cette syntaxe vous permet de créer des modèles à utiliser avec le publipostage qui utilisent des marqueurs de texte brut au lieu de champs de fusion. Ces marqueurs ressemblent à ceci : {{ FieldName }}
Syntaxe de l’objet.attribut
Vous pouvez facilement fusionner les attributs des champs en utilisant la syntaxe suivante :
{{ Address.Street }}
Cela fusionnera les données à partir de données XML qui ressemblent à ceci :
<Order> // <-- Current context is here.
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
<PhoneNumber>543 1234</PhoneNumber>
</Order>
Blocs Foreach
Vous pouvez fusionner des données provenant de plusieurs enregistrements à l’aide de la balise foreach. Cette méthode est similaire aux régions de publipostage avec des champs de fusion conventionnels. Vous pouvez imbriquer de tels blocs.
{{ #foreach Order }}
{{ Number }}
{{ Address.Street }}
{{ #foreach Item }}
{{ Description }} {{ Cost}} {{ Total }}
{{/foreach Item }}
{{ /foreach Order }}
Vous pouvez également mélanger ces champs et les placer dans d’autres champs Microsoft Word, tels que les champs SI ou Formule.
Bloc conditionnel
Vous pouvez utiliser le publipostage avec l’instruction IF à l’aide d’Aspose.Words Cloud. Le bloc IF s’exécute uniquement si l’expression booléenne qui lui est associée est vraie. La syntaxe de IF est indiquée ci-dessous.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
Le code pour effectuer un publipostage à l’aide du modèle « Moustache » est donné ci-dessous :
// Pour des exemples complets et des fichiers de données, veuillez consulter https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "VendorTemplate.doc";
var destFileName = "VendorTemplate_Out.docx";
string folder = null; // File exists at the root of the storage
var data = File.ReadAllText(@"c:\Data\" + "Vendors.xml");
// Télécharger le document d'entrée vers le stockage cloud
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
var postExecuteTemplateRequest = new PostExecuteTemplateRequest(fileName, data, folder, destFileName: destFileName);
var actual = wordsApi.PostExecuteTemplate(postExecuteTemplateRequest);
Insérer du code HTML pendant le publipostage
Les API executeMailMerge et executeTemplate prennent en charge l’insertion de code HTML dans un champ de fusion. Il vous suffit de vous assurer d’échapper les caractères HTML dans la chaîne de source de données et d’utiliser l’attribut “format”=“html” comme indiqué ci-dessous :
{
"dataSourceList": {
"contractDS": {
"contractDescription": {
"format":"html",
"htmlText": "<b>Test me 1<br><br><i>Test me 2<br><br><u>Test me 2</u></i></b><br>"
}
}
}
}
Le code suivant montre comment insérer du code HTML lors du publipostage :
// Pour des exemples complets et des fichiers de données, veuillez consulter https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
using System;
using System.IO;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;
namespace Aspose.Words.Cloud.Examples.CSharp
{
public class PopulateMailMergeTemplateWithHTMLData
{
public static void Run()
{
WordsApi wordsApi = new WordsApi(Constants.AppKey, Constants.AppSID);
try
{
string fileName = "template.doc";
string destName = "Out_PostDocumentExecuteMailMergeWithHTMLData.docx";
// Télécharger le document original sur le stockage cloud
wordsApi.UploadFile(new UploadFileRequest(File.Open("..\\..\\..\\Resources\\" + fileName, FileMode.Open), fileName, Constants.MYStorage));
string data = File.ReadAllText("..\\..\\..\\Resources\\TestPostDocumentExecuteMailMerge.txt", System.Text.Encoding.UTF8);
ExecuteMailMergeRequest request = new ExecuteMailMergeRequest(fileName, data, null, Constants.MYStorage, null, null, null, null, null, null, destName);
DocumentResponse result = wordsApi.ExecuteMailMerge(request);
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
}
}
Insérer des images pendant le publipostage
Vous pouvez également insérer des images dans un champ de fusion. Le facteur d’échelle des images peut être défini à l’aide de ‘%’, ‘px’ ou ’’ (mise à l’échelle proportionnelle).Le code permettant d’insérer des images lors du publipostage est donné ci-dessous :
// Pour des exemples complets et des fichiers de données, veuillez consulter https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "TestMailMergeWithImages.doc";
var destFileName = "TestMailMergeWithImages_Out.docx";
var data = File.ReadAllText(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + "MailMergeData.txt");
string folder = null; // File exists at the root of the storage
// Télécharger le document d'entrée vers le stockage cloud
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + fileName), null, null);
storageApi.PutCreate(request);
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
SDK Cloud
Bien que le code ci-dessus soit en .NET, les Aspose.Words Cloud SDK sont disponibles dans cinq langages différents : .NET, Java, Ruby, Python et Node.js. Par conséquent, vous pouvez facilement appeler les API de publipostage dans n’importe lequel de ces langages.