Customize Merge

Mail merging in GemBox.Document is very flexible and customizable. You can customize the MailMerge.FieldMerging event to suit your data importing requirements.

Your handler has access to a FieldMergingEventArgs object for each merging field. With it you can change the value or the format of the data that's being inserted, or replace the Run element's insertion with something else like Picture or Hyperlink elements.

Note that you can format the Date and Time or Numeric values with a simpler approach, by using formatting switches on the MERGEFIELD element itself (\@ for dates and \# for numbers).

The following example shows how you can perform a customized mail merge.

Word document generated from customizable mail merge
Screenshot of Word file created with customized merge
Upload your file (Drag file here)
using GemBox.Document;

class Program
{
    static void Main()
    {
        // If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = DocumentModel.Load("%InputFileName%");

        document.MailMerge.FieldMerging += (sender, e) =>
        {
            if (e.IsValueFound && e.Value != null)
            {
                switch (e.FieldName)
                {
                    case "CheckedField":
                        bool checkedValue = (bool)e.Value;
                        var run = (Run)e.Inline;
                        run.CharacterFormat.FontColor = checkedValue ? Color.Green : Color.Red;
                        run.Text = checkedValue ? "☑" : "☒";
                        break;

                    case "LinkField":
                        var linkValue = ((string Address, string DisplayText))e.Value;
                        e.Inline = new Hyperlink(e.Document, linkValue.Address, linkValue.DisplayText);
                        break;

                    case "ImageField":
                        var imagePath = e.Value.ToString();
                        e.Inline = new Picture(e.Document, imagePath);
                        break;
                }
            }
        };

        document.MailMerge.Execute(
            new
            {
                CheckedField = true,
                LinkField = (Address: "https://www.gemboxsoftware.com/", DisplayText: "GemBox Homepage"),
                ImageField = "%#Dices.png%"
            });

        document.Save("Merged Customizations Output.%OutputFileType%");
    }
}
Imports GemBox.Document

Module Program

    Sub Main()

        ' If using Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document = DocumentModel.Load("%InputFileName%")

        AddHandler document.MailMerge.FieldMerging,
            Sub(sender, e)
                If e.IsValueFound And e.Value IsNot Nothing Then
                    Select Case e.FieldName

                        Case "CheckedField"
                            Dim checkedValue As Boolean = DirectCast(e.Value, Boolean)
                            Dim run = DirectCast(e.Inline, Run)
                            run.CharacterFormat.FontColor = If(checkedValue, Color.Green, Color.Red)
                            run.Text = If(checkedValue, "☑", "☒")
                            Exit Select

                        Case "LinkField"
                            Dim linkValue = DirectCast(e.Value, (Address As String, DisplayText As String))
                            e.Inline = New Hyperlink(e.Document, linkValue.Address, linkValue.DisplayText)
                            Exit Select

                        Case "ImageField"
                            Dim imagePath = e.Value.ToString()
                            e.Inline = New Picture(e.Document, imagePath)
                            Exit Select

                    End Select
                End If
            End Sub

        document.MailMerge.Execute(
            New With
            {
                .CheckedField = True,
                .LinkField = (Address:="https://www.gemboxsoftware.com/", DisplayText:="GemBox Homepage"),
                .ImageField = "%#Dices.png%"
            })

        document.Save("Merged Customizations Output.%OutputFileType%")

    End Sub
End Module

Want more?

Next example GitHub

Check the next example or select an example from the menu. You can also download our examples from the GitHub.


Like it?

Download Buy

If you want to try the GemBox.Document yourself, you can download the free version. It delivers the same performance and set of features as the professional version, but with some operations limited. To remove the limitation, you need to purchase a license.