Mail Merge uitvoeren in een Word-document

Mail Merge is een functie van Microsoft Word voor het snel en eenvoudig maken van documenten zoals brieven, etiketten en enveloppen. Aspose.Words Cloud neemt de standaard mail merge en brengt deze vele stappen verder, waardoor het een volwaardige rapportageoplossing wordt waarmee u nog complexere documenten kunt genereren, zoals rapporten, catalogi, inventarissen en facturen. De voordelen van de Aspose.Words Cloud rapportageoplossing zijn:

• Rapporten ontwerpen in Microsoft Word met behulp van standaardvelden voor samenvoegen
• Definieer regio’s in het document die groeien, zoals detailrijen van een bestelling
• Afbeeldingen invoegen tijdens samenvoegen
• HTML invoegen tijdens samenvoegen

Basisstappen

Stappen om een mail merge uit te voeren zijn vrij eenvoudig. Eerst gebruikt u Microsoft Word om een Word-document te maken en te ontwerpen, normaal gesproken een sjabloon genoemd. Let op: het document hoeft geen Microsoft Word-sjabloon (.dot) te zijn, het kan een normaal .doc-document zijn. U voegt een aantal speciale velden in, samenvoegvelden genoemd, in de sjabloon op plaatsen waar u later gegevens uit uw gegevensbron wilt invoegen. Vervolgens voert u met Aspose.Words REST API een mail merge-bewerking uit. De mail merge-bewerking neemt gegevens uit uw gegevensbron en voegt deze samen in het document.

U kunt ook herhaalbare samenvoegingsgebieden in het document aanwijzen of speciale samenvoegingsvelden invoegen waarmee u andere inhoud, zoals afbeeldingen, kunt invoegen. Afhankelijk van hoe u samenvoegingsvelden en herhaalbare gebieden in het document instelt, groeit het document om meerdere records in uw gegevensbron te kunnen bevatten. Als u geen samenvoegingsgebieden gebruikt, lijkt de samenvoeging op de samenvoeging van Microsoft Word en wordt de volledige inhoud van het document herhaald voor elk record in de gegevensbron. Met herhaalbare samenvoegingsgebieden kunt u delen in een document aanwijzen die worden herhaald voor elk record in de gegevensbron. Als u bijvoorbeeld een tabelrij markeert als herhaalbaar gebied, wordt deze tabelrij herhaald, waardoor de tabel dynamisch groeit om al uw gegevens te kunnen bevatten.

Een document voorbereiden

Voordat u een mail merge uitvoert, moet u de documentsjabloon voorbereiden. U moet samenvoegvelden invoegen die worden vervangen door waarden uit uw gegevensbron.

Samenvoegvelden in een document invoegen

Samenvoegvelden in een document invoegen:

1. Open uw document in Microsoft Word.
2. Klik in het document op de plaats waar u een samenvoegveld wilt plaatsen.
3. Open het menu Invoegen en selecteer Veld om het dialoogvenster Veld te openen.
4. Selecteer MergeField in de lijst Veldnamen.
5. Voer in het tekstvak Veldnaam een naam in voor het samenvoegveld en klik op OK.

Omdat een samenvoegveld een normaal Microsoft Word-veld is, kunt u schakelen tussen het weergeven van veldcodes en resultaten in uw document in Microsoft Word met de sneltoets Alt+F9. Veldcodes worden weergegeven tussen accolades.

Eenvoudige samenvoeging van e-mail

Om uw sjabloon voor te bereiden op het uitvoeren van een eenvoudige samenvoeging (zonder gebieden, vergelijkbaar met de klassieke samenvoeging in Microsoft Word), hoeft u alleen maar een of meer samenvoegvelden in te voegen op de plaatsen waar u gegevens uit de gegevensbron wilt invullen.

Laten we eens kijken naar de Dinner Invitation demo. Het creëert een brief voor een lijst met cliënten die gedefinieerd zijn in de gegevensbron. De template bevat een aantal merge fields die gevuld zijn vanuit twee gegevensbronnen; met andere woorden, er worden twee mail merges na elkaar uitgevoerd. Eerst worden gegevens uit de eerste gegevensbron samengevoegd in de template. Deze gegevensbron bevat slechts één rij omdat dit informatie is over de inviter, dus de hele documentinhoud wordt niet herhaald en alleen de juiste velden worden gevuld met gegevens. Vervolgens wordt de tweede mail merge-bewerking uitgevoerd. De gegevensbron die het gebruikt bevat informatie over de cliënten. De hele template wordt herhaald voor elke gegevensrij en elke herhaalde kopie wordt gevuld met de gegevens van de overeenkomstige cliënt.

Het resultaat is een document dat bestaat uit vijf ingevulde, complete en gepersonaliseerde uitnodigingsbrieven (hieronder ziet u een fragment van de allereerste):

Zoals u kunt zien, is het mogelijk en soms nuttig om meer dan één samenvoegbewerking uit te voeren met dezelfde sjabloon om gegevens in fasen toe te voegen. U kunt NEXT-velden invoegen in het Word-document om ervoor te zorgen dat de mail merge-engine de volgende record uit de gegevensbron selecteert en doorgaat met samenvoegen. Wanneer de engine een NEXT-veld tegenkomt, selecteert deze gewoon de volgende record in de gegevensbron en gaat door met samenvoegen zonder inhoud te kopiëren. Dit kan worden gebruikt bij het maken van documenten zoals adreslabels.

Hieronder vindt u de code voor het uitvoeren van Simple Mail Merge:

// Voor complete voorbeelden en databestanden, ga naar 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

// Brondocument uploaden naar Cloudopslag
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);

// Voer de Mail Merge-bewerking voor de eerste keer uit
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);

// Voer de Mail Merge-bewerking een tweede keer uit
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);

Samenvoegen met regio’s

Als u dynamisch delen in het document wilt laten groeien, gebruikt u mail merge met regio’s. Om een mail merge-regio in het document op te geven, moet u twee mail merge-velden invoegen om het begin en einde van de mail merge-regio te markeren. Alle documentinhoud die in een mail merge-regio is opgenomen, wordt automatisch herhaald voor elke record in de gegevensbron.

Om het begin van een mail merge-regio te markeren, voegt u een MERGEFIELD in met de naam TableStart:MyTable, waarbij MyTable overeenkomt met de tag of sleutel in XML of JSON. Om het einde van de mail merge-regio te markeren, voegt u een andere MERGEFIELD in met de naam TableEnd:MyTable. Tussen deze markeervelden plaatst u samenvoegvelden die overeenkomen met de velden van uw gegevensbron. Deze samenvoegvelden worden gevuld met gegevens uit de eerste rij van de gegevensbron, vervolgens wordt de hele regio herhaald en worden de nieuwe velden gevuld met gegevens uit de tweede rij, enzovoort.

Volg deze eenvoudige regels bij het markeren van een regio:

• De velden TableStart en TableEnd moeten zich in dezelfde sectie in het document bevinden
• Als ze binnen een tabel worden gebruikt, moeten TableStart en TableEnd zich in dezelfde rij in de tabel bevinden
• Samenvoegingsgebieden kunnen in elkaar worden genest
• Samenvoegingsgebieden moeten goed gevormd zijn (er is altijd een paar overeenkomende TableStart en TableEnd met dezelfde tabelnaam)

Kijk bijvoorbeeld eens naar de Item Catalog demo. Hier is een fragment van een regio die is voorbereid voor mail merge:

Let op dat de markeringsvelden TableStart:Item en TableEnd:Item beide in dezelfde rij van de Word-tabel worden geplaatst. Na het uitvoeren van de samenvoeging is dit het resultaat:

Hieronder vindt u de code voor het uitvoeren van Mail Merge met regio’s:

// Voor complete voorbeelden en databestanden, ga naar 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

// Upload invoerdocument naar Cloudopslag
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);

Mail Merge met behulp van de ‘Mustache’-sjabloonsyntaxis

Met deze syntaxis kunt u sjablonen maken voor gebruik met samenvoeging van e-mail die markeringen voor platte tekst gebruiken in plaats van samenvoegvelden. Deze markeringen zien er als volgt uit: {{ FieldName }}

Object.Attribute-syntaxis

U kunt eenvoudig kenmerken van velden samenvoegen met behulp van de volgende syntaxis:

  {{ Address.Street }}  

Hiermee worden gegevens uit XML-gegevens samengevoegd, die er als volgt uitzien:

<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>  

Foreach-blokken

U kunt gegevens uit meerdere records samenvoegen met behulp van de foreach-tag. Dit is vergelijkbaar met mail merge-regio’s met conventionele merge-velden. U kunt dergelijke blokken nesten.

{{ #foreach Order }}  
  {{ Number }}  
    {{ Address.Street }}  
      {{ #foreach Item }}  
        {{ Description }} {{ Cost}} {{ Total }}  
      {{/foreach Item }}  
{{ /foreach Order }} 

U kunt deze velden ook combineren en in andere Microsoft Word-velden plaatsen, zoals ALS- of Formulevelden.

Voorwaardelijk blok

U kunt mail merge gebruiken met IF-statement met behulp van Aspose.Words Cloud. Het IF-blok wordt alleen uitgevoerd als de Booleaanse expressie die eraan is gekoppeld true is. De syntaxis van IF wordt hieronder weergegeven.

{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }

Hieronder vindt u de code voor het uitvoeren van een samenvoegbewerking met behulp van de sjabloon ‘Mustache’:

// Voor complete voorbeelden en databestanden, ga naar 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");

// Upload invoerdocument naar Cloudopslag
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);

HTML invoegen tijdens samenvoegen

Zowel executeMailMerge als executeTemplate API’s bieden ondersteuning voor het invoegen van HTML in een samenvoegveld. U hoeft er alleen voor te zorgen dat u HTML-tekens in de data source string escapet en het kenmerk “format”=“html” gebruikt zoals hieronder weergegeven:

{     
  "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>"         
      }       
    }     
  }   
}

De volgende code laat zien hoe u HTML kunt invoegen tijdens een samenvoeging:

// Voor complete voorbeelden en databestanden, ga naar 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";

				// Upload origineel document naar Cloudopslag
				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());
			}
		}
	}
}

Afbeeldingen invoegen tijdens samenvoegen

U kunt ook afbeeldingen invoegen in een samenvoegveld. De schaalfactor voor afbeeldingen kan worden ingesteld met ‘%’, ‘px’ of ’’ (proportioneel schalen).De code om afbeeldingen in te voegen tijdens Mail Merge staat hieronder:

// Voor complete voorbeelden en databestanden, ga naar 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

// Upload invoerdocument naar Cloudopslag
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);

Cloud-SDK’s

Hoewel de bovenstaande code in .NET is, zijn Aspose.Words Cloud SDKs beschikbaar in vijf verschillende talen: .NET, Java, Ruby, Python en Node.js. Daarom kunt u eenvoudig Mail Merge API’s in elk van deze talen aanroepen.

Voorgestelde post:

• Combineer Word-documenten met .NET REST API
• Converteer ODT naar DOC met .NET REST API
• Converteer Word (DOC, DOCX) naar JPG met behulp van .NET REST API