La combinación de correspondencia es una función de Microsoft Word que permite crear documentos como cartas, etiquetas y sobres de forma rápida y sencilla. Aspose.Words Cloud toma la combinación de correspondencia estándar y la lleva muchos pasos más allá, convirtiéndola en una solución de generación de informes completa que le permite generar documentos aún más complejos, como informes, catálogos, inventarios y facturas. Las ventajas de la solución de generación de informes Aspose.Words Cloud son:
- Diseñar informes en Microsoft Word utilizando campos de combinación de correspondencia estándar
- Defina regiones en el documento que crezcan, como las filas de detalles de un pedido.
- Insertar imágenes durante la combinación de correspondencia
- Insertar HTML durante la combinación de correspondencia
Pasos básicos
Los pasos para realizar una combinación de correspondencia son bastante sencillos. Primero, utilice Microsoft Word para crear y diseñar un documento de Word, normalmente llamado plantilla. Tenga en cuenta que el documento no tiene que ser una plantilla de Microsoft Word (.dot), puede ser un documento .doc normal. Inserte algunos campos especiales llamados campos de combinación en la plantilla en los lugares donde desea que se inserten posteriormente los datos de su fuente de datos. Luego, con la API REST de Aspose.Words, ejecute una operación de combinación de correspondencia. La operación de combinación de correspondencia tomará los datos de su fuente de datos y los combinará en el documento.
También puede designar regiones de combinación repetibles en el documento o insertar campos de combinación especiales que le permitan insertar otro contenido, como imágenes. Según cómo configure los campos de combinación de correspondencia y las regiones repetibles dentro del documento, el documento crecerá para dar cabida a varios registros en su fuente de datos. Si no utiliza regiones de combinación de correspondencia, la combinación de correspondencia será similar a la combinación de correspondencia de Microsoft Word y todo el contenido del documento se repetirá para cada registro en la fuente de datos. Si utiliza regiones de combinación de correspondencia repetibles, puede designar partes dentro de un documento que se repetirán para cada registro en la fuente de datos. Por ejemplo, si marca una fila de tabla como región repetible, esta fila de tabla se repetirá, lo que hará que la tabla crezca dinámicamente para dar cabida a todos sus datos.
Preparar un documento
Antes de ejecutar una combinación de correspondencia, debe preparar la plantilla del documento. Debe insertar campos de combinación que se reemplazarán con valores de su fuente de datos.
Insertar campos de combinación en un documento
Para insertar campos de combinación en un documento:
- Abra su documento en Microsoft Word.
- En el documento, haga clic donde desee colocar un campo de combinación.
- Abra el menú Insertar y seleccione Campo para abrir el cuadro de diálogo Campo.
- En la lista Nombres de campos, seleccione MergeField.
- En el cuadro de texto Nombre del campo, ingrese un nombre para el campo de combinación y presione Aceptar.
Dado que un campo de combinación es un campo normal de Microsoft Word, puede alternar entre mostrar los códigos de campo y los resultados en su documento en Microsoft Word mediante el atajo de teclado Alt+F9. Los códigos de campo aparecen entre llaves.
Combinación de correspondencia sencilla
Para preparar su plantilla para realizar una combinación de correspondencia simple (sin regiones, similar a la combinación de correspondencia clásica disponible en Microsoft Word), solo debe insertar uno o más campos de combinación en los lugares donde desea que se completen con datos de la fuente de datos.
Veamos la demostración de la invitación a cenar. Crea una carta para una lista de clientes definida en la fuente de datos. La plantilla contiene una serie de campos de combinación que se rellenan a partir de dos fuentes de datos; en otras palabras, se realizan dos combinaciones de correspondencia una tras otra. Primero, se combinan los datos de la primera fuente de datos en la plantilla. Esta fuente de datos contiene solo una fila porque se trata de información sobre el invitador, por lo que no se repite todo el contenido del documento y solo se rellenan con datos los campos correspondientes. Luego, se ejecuta la segunda operación de combinación de correspondencia. La fuente de datos que utiliza contiene información sobre los clientes. Se repite toda la plantilla para cada fila de datos y cada copia repetida se rellena con los datos del cliente correspondiente.
Como resultado tenemos un documento que consta de cinco cartas de invitación rellenadas, completas y personalizadas (a continuación se muestra un fragmento de la primera de ellas):
Como puede ver, es posible, y a veces útil, realizar más de una operación de combinación con la misma plantilla para agregar datos en etapas. Puede insertar campos NEXT en el documento de Word para que el motor de combinación de correspondencia seleccione el siguiente registro de la fuente de datos y continúe con la combinación. Cuando el motor encuentra un campo NEXT, simplemente selecciona el siguiente registro en la fuente de datos y continúa con la combinación sin copiar ningún contenido. Esto se puede utilizar al crear documentos como etiquetas de correo.
El código para realizar una combinación de correspondencia simple se proporciona a continuación:
// Para obtener ejemplos completos y archivos de datos, visite 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
// Subir documento fuente al almacenamiento en la nube
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
// Ejecutar la operación de combinación de correspondencia por primera vez
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
// Ejecutar la operación de combinación de correspondencia por segunda vez
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);
Combinar correspondencia con regiones
Si desea aumentar dinámicamente partes dentro del documento, utilice la combinación de correspondencia con regiones. Para especificar una región de combinación de correspondencia en el documento, debe insertar dos campos de combinación de correspondencia para marcar el comienzo y el final de la región de combinación de correspondencia. Todo el contenido del documento que se incluye dentro de una región de combinación de correspondencia se repetirá automáticamente para cada registro en la fuente de datos.
Para marcar el comienzo de una región de combinación de correspondencia, inserte un MERGEFIELD con el nombre TableStart:MyTable, donde MyTable corresponde a la etiqueta o clave en XML o JSON respectivamente. Para marcar el final de la región de combinación de correspondencia, inserte otro MERGEFIELD con el nombre TableEnd:MyTable. Entre estos campos de marcado, coloque los campos de combinación que correspondan a los campos de su fuente de datos. Estos campos de combinación se completarán con datos de la primera fila de la fuente de datos, luego se repetirá toda la región y los nuevos campos se completarán con datos de la segunda fila, y así sucesivamente.
Siga estas sencillas reglas al marcar una región:
- Los campos TableStart y TableEnd deben estar dentro de la misma sección en el documento
- Si se usa dentro de una tabla, TableStart y TableEnd deben estar dentro de la misma fila en la tabla.
- Las regiones de combinación de correspondencia se pueden anidar unas dentro de otras
- Las regiones de combinación de correspondencia deben estar bien formadas (siempre hay un par de TableStart y TableEnd coincidentes con el mismo nombre de tabla)
A modo de ejemplo, eche un vistazo a la demostración del catálogo de artículos. A continuación, se muestra un fragmento de una región preparada para la combinación de correspondencia:
Tenga en cuenta que ambos campos de marcado TableStart:Item y TableEnd:Item se colocan dentro de la misma fila de la tabla de Word. Después de ejecutar la combinación de correspondencia, este es el resultado:
El código para realizar la combinación de correspondencia con regiones se proporciona a continuación:
// Para obtener ejemplos completos y archivos de datos, visite 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
// Subir documento de entrada al almacenamiento en la nube
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);
Combinar correspondencia usando la sintaxis de la plantilla ‘Mustache’
Esta sintaxis le permite crear plantillas para usar con la combinación de correspondencia que utilizan marcadores de texto sin formato en lugar de campos de combinación. Estos marcadores tienen el siguiente aspecto: {{ FieldName }}
Sintaxis de objeto.atributo
Puede fusionar fácilmente atributos de campos utilizando la siguiente sintaxis:
{{ Address.Street }}
Esto fusionará datos de datos XML que se verán así:
<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>
Bloques Foreach
Puede combinar datos de varios registros mediante la etiqueta foreach. Esto es similar a las regiones de combinación de correspondencia con campos de combinación convencionales. Puede anidar dichos bloques.
{{ #foreach Order }}
{{ Number }}
{{ Address.Street }}
{{ #foreach Item }}
{{ Description }} {{ Cost}} {{ Total }}
{{/foreach Item }}
{{ /foreach Order }}
También puede mezclar estos campos y colocarlos dentro de otros campos de Microsoft Word, como los campos SI o de Fórmula.
Bloque condicional
Puede utilizar la combinación de correspondencia con la declaración IF mediante Aspose.Words Cloud. El bloque IF se ejecuta solo si la expresión booleana asociada con él es verdadera. La sintaxis de IF se muestra a continuación.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
El código para realizar la combinación de correspondencia utilizando la plantilla ‘Mustache’ se proporciona a continuación:
// Para obtener ejemplos completos y archivos de datos, visite 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");
// Subir documento de entrada al almacenamiento en la nube
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);
Insertar HTML durante la combinación de correspondencia
Las API executeMailMerge y executeTemplate brindan soporte para insertar HTML en un campo de combinación. Solo debe asegurarse de escapar los caracteres HTML en la cadena de origen de datos y usar el atributo “format”=“html” como se muestra a continuación:
{
"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>"
}
}
}
}
El siguiente código muestra cómo insertar HTML durante la combinación de correspondencia:
// Para obtener ejemplos completos y archivos de datos, visite 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";
// Subir documento original al almacenamiento en la nube
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());
}
}
}
}
Insertar imágenes durante la combinación de correspondencia
También puede insertar imágenes en un campo de combinación. El factor de escala de las imágenes se puede configurar utilizando ‘%’, ‘px’ o ’’’’ (escala proporcional).El código para insertar imágenes durante la combinación de correspondencia se proporciona a continuación:
// Para obtener ejemplos completos y archivos de datos, visite 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
// Subir documento de entrada al almacenamiento en la nube
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 de la nube
Aunque el código anterior está en .NET, los SDK de Aspose.Words Cloud están disponibles en cinco lenguajes diferentes: .NET, Java, Ruby, Python y Node.js. Por lo tanto, puede llamar cómodamente a las API de combinación de correspondencia en cualquiera de estos lenguajes.