Mail Merge è una funzionalità di Microsoft Word per creare rapidamente e facilmente documenti come lettere, etichette e buste. Aspose.Words Cloud prende la standard mail merge e la fa progredire di molti passi, trasformandola in una soluzione di reporting completa che consente di generare documenti ancora più complessi come report, cataloghi, inventari e fatture. I vantaggi della soluzione di reporting Aspose.Words Cloud sono:
- Progetta report in Microsoft Word utilizzando i campi di unione di posta standard
- Definisci le regioni nel documento che crescono, come le righe di dettaglio di un ordine
- Inserire immagini durante la stampa unione
- Inserisci HTML durante la stampa unione
Passaggi di base
I passaggi per eseguire una stampa unione sono piuttosto semplici. Innanzitutto, si usa Microsoft Word per creare e progettare un documento Word, normalmente chiamato modello. Si noti che il documento non deve essere un modello Microsoft Word (.dot), può essere un normale documento .doc. Si inseriscono alcuni campi speciali chiamati campi di unione nel modello nei punti in cui si desidera che i dati dalla propria origine dati vengano inseriti in seguito. Quindi con Aspose.Words REST API, si esegue un’operazione di stampa unione. L’operazione di stampa unione prenderà i dati dalla propria origine dati e li unirà al documento.
Puoi anche designare regioni di unione ripetibili nel documento o inserire campi di unione speciali che ti consentono di inserire altri contenuti, come immagini. A seconda di come imposti i campi di unione e le regioni ripetibili all’interno del documento, il documento crescerà per ospitare più record nella tua origine dati. Se non utilizzi regioni di unione, la stampa unione sarà simile alla stampa unione di Microsoft Word e l’intero contenuto del documento verrà ripetuto per ogni record nella tua origine dati. Utilizzando regioni di unione ripetibili, puoi designare porzioni all’interno di un documento che verranno ripetute per ogni record nella tua origine dati. Ad esempio, se contrassegni una riga di tabella come regione ripetibile, questa riga di tabella verrà ripetuta, causando la crescita dinamica della tabella per ospitare tutti i tuoi dati.
Preparare un documento
Prima di eseguire una stampa unione, devi preparare il modello di documento. Dovresti inserire campi di unione che saranno sostituiti con valori dalla tua origine dati.
Inserimento di campi di unione in un documento
Per inserire campi unione in un documento:
- Apri il documento in Microsoft Word.
- Nel documento, fare clic nel punto in cui si desidera posizionare un campo unione.
- Aprire il menu Inserisci e selezionare Campo per aprire la finestra di dialogo Campo.
- Dall’elenco Nomi campi, selezionare MergeField.
- Nella casella di testo Nome campo, immettere un nome per il campo di unione e premere OK.
Poiché un campo di unione è un normale campo di Microsoft Word, puoi alternare la visualizzazione dei codici di campo e dei risultati nel tuo documento in Microsoft Word utilizzando la scorciatoia da tastiera Alt+F9. I codici di campo vengono visualizzati tra parentesi graffe.
Semplice unione di posta
Per preparare il modello per eseguire una semplice stampa unione (senza aree, simile alla classica stampa unione disponibile in Microsoft Word), è sufficiente inserire uno o più campi unione nei punti in cui si desidera che vengano inseriti i dati provenienti dall’origine dati.
Diamo un’occhiata alla demo di Dinner Invitation. Crea una lettera per un elenco di clienti definiti nell’origine dati. Il modello contiene un certo numero di campi di unione che vengono popolati da due origini dati; in altre parole, vengono eseguite due unioni di posta una dopo l’altra. Innanzitutto, i dati dalla prima origine dati vengono uniti nel modello. Questa origine dati contiene solo una riga perché si tratta di informazioni sull’invitante, quindi l’intero contenuto del documento non viene ripetuto e solo i campi appropriati vengono riempiti con i dati. Quindi viene eseguita la seconda operazione di unione di posta. L’origine dati che utilizza contiene informazioni sui clienti. L’intero modello viene ripetuto per ogni riga di dati e ogni copia ripetuta viene popolata con i dati del cliente corrispondente.
Di conseguenza, abbiamo un documento composto da cinque lettere di invito compilate, complete e personalizzate (di seguito è riportato un frammento della prima):
Come puoi vedere, è possibile, e a volte utile, eseguire più di un’operazione di unione con lo stesso modello per aggiungere dati in più fasi. Puoi inserire campi NEXT nel documento Word per far sì che il motore di unione selezioni il record successivo dall’origine dati e continui l’unione. Quando il motore incontra un campo NEXT, seleziona semplicemente il record successivo nell’origine dati e continua l’unione senza copiare alcun contenuto. Questo può essere utilizzato quando si creano documenti come etichette postali.
Di seguito è riportato il codice per eseguire la stampa unione semplice:
// Per esempi completi e file di dati, visitare 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
// Carica il documento sorgente su Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
// Esegui l'operazione di unione di posta per la prima volta
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
// Esegui l'operazione di unione di posta per la seconda volta
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);
Stampa unione con regioni
Se vuoi aumentare dinamicamente le porzioni all’interno del documento, usa la stampa unione con regioni. Per specificare una regione di stampa unione nel documento, devi inserire due campi di stampa unione per contrassegnare l’inizio e la fine della regione di stampa unione. Tutto il contenuto del documento incluso in una regione di stampa unione verrà ripetuto automaticamente per ogni record nell’origine dati.
Per contrassegnare l’inizio di una regione di stampa unione, inserisci un MERGEFIELD con il nome TableStart:MyTable, dove MyTable corrisponde al tag o alla chiave in XML o JSON rispettivamente. Per contrassegnare la fine della regione di stampa unione, inserisci un altro MERGEFIELD con il nome TableEnd:MyTable. Tra questi campi di marcatura, posiziona i campi di unione che corrispondono ai campi della tua origine dati. Questi campi di unione saranno popolati con i dati della prima riga dell’origine dati, quindi l’intera regione sarà ripetuta e i nuovi campi saranno popolati con i dati della seconda riga e così via.
Quando si contrassegna una regione, seguire queste semplici regole:
- I campi TableStart e TableEnd devono essere all’interno della stessa sezione del documento
- Se utilizzati all’interno di una tabella, TableStart e TableEnd devono essere all’interno della stessa riga della tabella
- Le regioni di unione di posta possono essere annidate l’una dentro l’altra
- Le regioni di unione di posta devono essere ben formate (c’è sempre una coppia di TableStart e TableEnd corrispondenti con lo stesso nome di tabella)
Come esempio, date un’occhiata alla demo di Item Catalog. Ecco un frammento di una regione preparata per la stampa unione:
Si noti che entrambi i campi di marcatura TableStart:Item e TableEnd:Item sono posizionati all’interno della stessa riga della tabella di Word. Dopo aver eseguito la stampa unione, ecco il risultato:
Di seguito è riportato il codice per eseguire la stampa unione con regioni:
// Per esempi completi e file di dati, visitare 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
// Carica il documento di input su Cloud Storage
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);
Stampa unione utilizzando la sintassi del modello ‘Mustache’
Questa sintassi consente di creare modelli da utilizzare con la stampa unione che utilizzano marcatori di testo normale anziché campi di unione. Questi marcatori hanno questo aspetto: {{ FieldName }}
Sintassi Object.Attribute
È possibile unire facilmente gli attributi dei campi utilizzando la seguente sintassi:
{{ Address.Street }}
Questo unirà i dati dai dati XML che si presentano in questo modo:
<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>
Blocchi Foreach
Puoi unire dati da più record usando il tag foreach. Questo è simile alle regioni di unione di posta con campi di unione convenzionali. Puoi annidare tali blocchi.
{{ #foreach Order }}
{{ Number }}
{{ Address.Street }}
{{ #foreach Item }}
{{ Description }} {{ Cost}} {{ Total }}
{{/foreach Item }}
{{ /foreach Order }}
È anche possibile combinare questi campi e inserirli all’interno di altri campi di Microsoft Word, ad esempio i campi SE o Formula.
Blocco condizionale
È possibile usare la stampa unione con l’istruzione IF usando Aspose.Words Cloud. Il blocco IF viene eseguito solo se l’espressione booleana associata è vera. La sintassi di IF è mostrata di seguito.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
Di seguito è riportato il codice per eseguire la stampa unione utilizzando il modello ‘Mustache’:
// Per esempi completi e file di dati, visitare 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");
// Carica il documento di input su Cloud Storage
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);
Inserisci HTML durante la stampa unione
Entrambe le API executeMailMerge e executeTemplate forniscono supporto per l’inserimento di HTML in un campo di unione. Devi solo assicurarti di usare l’escape dei caratteri HTML nella stringa di origine dati e di usare l’attributo “format”=“html” come mostrato di seguito:
{
"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>"
}
}
}
}
Il codice seguente mostra come inserire codice HTML durante la stampa unione:
// Per esempi completi e file di dati, visitare 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";
// Carica il documento originale su Cloud Storage
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());
}
}
}
}
Inserisci immagini durante la stampa unione
È anche possibile inserire immagini in un campo di unione. Il fattore di scala per le immagini può essere impostato utilizzando ‘%’, ‘px’ o ’’ (scala proporzionale).Il codice per inserire immagini durante la stampa unione è riportato di seguito:
// Per esempi completi e file di dati, visitare 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
// Carica il documento di input su Cloud Storage
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
Sebbene il codice sopra riportato sia in .NET, Aspose.Words Cloud SDK sono disponibili in cinque linguaggi diversi: .NET, Java, Ruby, Python e Node.js. Pertanto, puoi comodamente chiamare le API di Mail Merge in uno qualsiasi di questi linguaggi.