FieldMergingArgs Class

Provides data for the MergeField event.

Inheritance Hierarchy

Namespace:  Aspose.Words.MailMerging
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 20.8.0

Syntax

public class FieldMergingArgs : FieldMergingArgsBase

The FieldMergingArgs type exposes the following members.

Properties

  NameDescription
Public propertyCode exampleDocument
Returns the Document object for which the mail merge is performed.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleDocumentFieldName
Gets the name of the merge field as specified in the document.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleField
Gets the object that represents the current merge field.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldName
Gets the name of the merge field in the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldValue
Gets or sets the value of the field from the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleRecordIndex
Gets the zero based index of the record that is being merged.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleTableName
Gets the name of the data table for the current merge operation or empty string if the name is not available.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleText
Gets or sets the text that will be inserted into the document for the current merge field.

Methods

  NameDescription
Public methodEquals (Inherited from Object.)
Public methodGetHashCode (Inherited from Object.)
Public methodGetType (Inherited from Object.)
Public methodToString (Inherited from Object.)

Remarks

The MergeField event occurs during mail merge when a simple mail merge field is encountered in the document. You can respond to this event to return text for the mail merge engine to insert into the document.

Examples

Shows how to mail merge HTML data into a document.
public void InsertHtml()
{
    Document doc = new Document(MyDir + "Field sample - MERGEFIELD.docx");

    // Add a handler for the MergeField event
    doc.MailMerge.FieldMergingCallback = new HandleMergeFieldInsertHtml();

    const string html = @"<html>
            <h1>Hello world!</h1>
    </html>";

    // Execute mail merge
    doc.MailMerge.Execute(new string[] { "htmlField1" }, new object[] { html });

    // Save resulting document with a new name
    doc.Save(ArtifactsDir + "MailMergeEvent.InsertHtml.docx");
}

private class HandleMergeFieldInsertHtml : IFieldMergingCallback
{
    /// <summary>
    /// This is called when merge field is actually merged with data in the document.
    /// </summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
        if (args.DocumentFieldName.StartsWith("html") && args.Field.GetFieldCode().Contains("\\b"))
        {
            FieldMergeField field = args.Field;

            // Insert the text for this merge field as HTML data, using DocumentBuilder
            DocumentBuilder builder = new DocumentBuilder(args.Document);
            builder.MoveToMergeField(args.DocumentFieldName);
            builder.Write(field.TextBefore);
            builder.InsertHtml((string) args.FieldValue);

            // The HTML text itself should not be inserted
            // We have already inserted it as an HTML
            args.Text = "";
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Do nothing
    }
}

See Also