Mail Merge in Blazor Rich Text Editor

• Jun 24, 2024
• 4 minutes to read

The mail merge functionality allows you to bind the control to an external data source, preview dynamic content in the opened document template, and generate resulting documents with merged data.

Run Demo

Follow the steps below to execute a mail merge operation.

Step 1. Specify a Data Source

Assign an external data source to the Data property to bind this data source’s data to a document template.

@inject NwindDataService NwindDataService
<DxRichEdit>
    <MailMergeSettings>
        <DxMailMergeSettings Data="@DataSource"/>
    </MailMergeSettings>
</DxRichEdit>

@code {
    IEnumerable<Employee> DataSource;
    protected override async Task OnInitializedAsync() {
        DataSource = await NwindDataService.GetEmployeesAsync();
        await base.OnInitializedAsync();
    }
}

Show the data sources

Employee.cs

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
namespace BlazorDemo.Data.Northwind {
    public partial class Employee {
        public Employee() {
            this.Orders = new List<Order>();
        }
        public int EmployeeId { get; set; }
        public string LastName { get; set; }
        public string FirstName { get; set; }
        public string Title { get; set; }
        public string TitleOfCourtesy { get; set; }
        public Nullable<System.DateTime> BirthDate { get; set; }
        public Nullable<System.DateTime> HireDate { get; set; }
        public string Address { get; set; }
        public string City { get; set; }
        public string Region { get; set; }
        public string PostalCode { get; set; }
        public string Country { get; set; }
        public string HomePhone { get; set; }
        public string Extension { get; set; }
        public string Notes { get; set; }
        public Nullable<int> ReportsTo { get; set; }
        public string PhotoPath { get; set; }
        public virtual ICollection<Order> Orders { get; set; }
        public string Text => $"{FirstName} {LastName} ({Title})";
        public string ImageFileName => $"Employees/{EmployeeId}.jpg";
    }
}

The Rich Text Editor cannot get data from a nested field. If your data source contains complex fields, modify the data source before binding.

Step 2. Create a Document Template

Add { MERGEFIELD "field name" } fields to a document to create a document template. A MERGEFIELD is a placeholder for the information that is merged from the bound data source. The field’s field name parameter should refer to the name of the data source’s field.

Call a CreateAsync method overload to add a MERGEFIELD field to a document. The following code snippet inserts a MERGEFIELD that refers to the City data field at the caret position:

<DxRichEdit @ref="@richEdit" @bind-Selection=@selection />

@code {
    DxRichEdit richEdit;
    Selection selection;

    protected override async Task OnAfterRenderAsync(bool firstRender) {
        if (firstRender)
            await InitializeDocument();
        await base.OnAfterRenderAsync(firstRender);
    }

    ValueTask<Field> InitializeDocument() {
        return rich.DocumentAPI.Fields.CreateAsync(selection.CaretPosition, "MERGEFIELD City");
    }
}

Note

The MERGEFIELD field can only substitute plain text. To insert formatted content, use the DOCVARIABLE field instead.

Step 3. Preview Merged Data

The Rich Text Editor allows you to preview merged data records in the opened document template.

Set the ViewMergedData property to true to display merged data. The ActiveRecord property specifies the currently visible data record and allows you to navigate through records.

@inject NwindDataService NwindDataService
<DxRichEdit>
    <MailMergeSettings>
        <DxMailMergeSettings Data="@DataSource" ViewMergedData="true" ActiveRecord="1"/>
    </MailMergeSettings>
</DxRichEdit>

@code {
    IEnumerable<Employee> DataSource;
    protected override async Task OnInitializedAsync() {
        DataSource = await NwindDataService.GetEmployeesAsync();
        await base.OnInitializedAsync();
    }
}

Step 4. Merge the Document

Call one of the Document‘s MailMergeAsync method overloads to execute a mail merge operation. These overloads merge all or selected records of the bound data source to the document template, separate merged ranges with paragraphs or sections, and return the resulting document as a byte array. You can use this array to process the document further.

The following code snippet executes a mail merge operation and load the resulting document to the Rich Text Editor:

<DxRichEdit @ref=richEdit>
   <MailMergeSettings>
        <DxMailMergeSettings Data="@DataSource" ViewMergedData="true" ActiveRecord="1"/>
    </MailMergeSettings>
</DxRichEdit>

@code {
    IEnumerable<Employee> DataSource;
    async void ExecuteMailMerge(){ 
        byte[] result = await richEdit.DocumentAPI.MailMergeAsync(DocumentFormat.OpenXml);
        await richEdit.LoadDocumentAsync(result, DocumentFormat.OpenXml);
    }
}

Mail Merge Ribbon Tab

When the Rich Text Editor is bound to a data source, the control enables items in the Mail Merge ribbon tab that allow users to do the following:

• Insert MERGEFIELD fields from the bound data source.
• View merged data.
• Navigate through data source records.
• Merge the document and download the result.