Aspose::Words::MailMerging::FieldMergingArgs class

FieldMergingArgs class

Provides data for the MergeField event. To learn more, visit the Mail Merge and Reporting documentation article.

class FieldMergingArgs : public Aspose::Words::MailMerging::FieldMergingArgsBase

Methods

MethodDescription
get_Document() constReturns the Document object for which the mail merge is performed.
get_DocumentFieldName() constGets the name of the merge field as specified in the document.
get_Field() constGets the object that represents the current merge field.
get_FieldName() constGets the name of the merge field in the data source.
get_FieldValue() constGets the value of the field from the data source.
get_RecordIndex() constGets the zero based index of the record that is being merged.
get_TableName() constGets the name of the data table for the current merge operation or empty string if the name is not available.
get_Text() constGets or sets the text that will be inserted into the document for the current merge field.
GetType() const override
Is(const System::TypeInfo&) const override
set_FieldValue(const System::SharedPtr<System::Object>&)Sets the value of the field from the data source.
set_Text(const System::String&)Setter for Aspose::Words::MailMerging::FieldMergingArgs::get_Text.
static Type()

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 execute a mail merge with a custom callback that handles merge data in the form of HTML documents.

void MergeHtml()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);

    builder->InsertField(u"MERGEFIELD  html_Title  \\b Content");
    builder->InsertField(u"MERGEFIELD  html_Body  \\b Content");

    ArrayPtr<SharedPtr<System::Object>> mergeData = MakeArray<SharedPtr<System::Object>>(
        {System::ObjectExt::Box<String>(String(u"<html>") + u"<h1>" + u"<span style=\"color: #0000ff; font-family: Arial;\">Hello World!</span>" +
                                        u"</h1>" + u"</html>"),
         System::ObjectExt::Box<String>(
             String(u"<html>") + u"<blockquote>" +
             u"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>" +
             u"</blockquote>" + u"</html>")});

    doc->get_MailMerge()->set_FieldMergingCallback(MakeObject<ExMailMergeEvent::HandleMergeFieldInsertHtml>());
    doc->get_MailMerge()->Execute(MakeArray<String>({u"html_Title", u"html_Body"}), mergeData);

    doc->Save(ArtifactsDir + u"MailMergeEvent.MergeHtml.docx");
}

class HandleMergeFieldInsertHtml : public IFieldMergingCallback
{
private:
    void FieldMerging(SharedPtr<FieldMergingArgs> args) override
    {
        if (args->get_DocumentFieldName().StartsWith(u"html_") && args->get_Field()->GetFieldCode().Contains(u"\\b"))
        {
            // Add parsed HTML data to the document's body.
            auto builder = MakeObject<DocumentBuilder>(args->get_Document());
            builder->MoveToMergeField(args->get_DocumentFieldName());
            builder->InsertHtml(System::ObjectExt::Unbox<String>(args->get_FieldValue()));

            // Since we have already inserted the merged content manually,
            // we will not need to respond to this event by returning content via the "Text" property.
            args->set_Text(String::Empty);
        }
    }

    void ImageFieldMerging(SharedPtr<ImageFieldMergingArgs> args) override
    {
        // Do nothing.
    }
};

See Also

Aspose::Words::MailMerging::FieldMergingArgsBase class