Aspose::Words::MailMerging::FieldMergingArgs Class Reference

Detailed Description

Provides data for the MergeField event.

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.

See also
Aspose::Words::MailMerging::IFieldMergingCallback
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
{
public:
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.
}
};

#include <Aspose.Words.Cpp/MailMerging/FieldMergingArgs.h>

+ Inheritance diagram for Aspose::Words::MailMerging::FieldMergingArgs:

Public Member Functions

String get_Text () const
 Gets or sets the text that will be inserted into the document for the current merge field. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
void set_Text (String value)
 Setter for get_Text. More...
 
- Public Member Functions inherited from FieldMergingArgsBase
SharedPtr< Documentget_Document () const
 Returns the Document object for which the mail merge is performed. More...
 
String get_DocumentFieldName () const
 Gets the name of the merge field as specified in the document. More...
 
SharedPtr< FieldMergeFieldget_Field () const
 Gets the object that represents the current merge field. More...
 
String get_FieldName () const
 Gets the name of the merge field in the data source. More...
 
SharedPtr< Objectget_FieldValue () const
 Gets the value of the field from the data source. More...
 
int32_t get_RecordIndex () const
 Gets the zero based index of the record that is being merged. More...
 
String get_TableName () const
 Gets the name of the data table for the current merge operation or empty string if the name is not available. More...
 
void set_FieldValue (SharedPtr< Object > value)
 Sets the value of the field from the data source. More...
 

Static Public Member Functions

static const TypeInfoType ()
 
- Static Public Member Functions inherited from FieldMergingArgsBase
static const TypeInfoType ()
 

Member Function Documentation

◆ get_Text()

System::String Aspose::Words::MailMerging::FieldMergingArgs::get_Text ( ) const

Gets or sets the text that will be inserted into the document for the current merge field.

When your event handler is called, this property is set to null.

If you leave Text as null, the mail merge engine will insert FieldValue in place of the merge field.

If you set Text to any string (including empty), the string will be inserted into the document in place of the merge field.

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
{
public:
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.
}
};

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::MailMerging::FieldMergingArgs::GetType ( ) const
overridevirtual

◆ Is()

virtual bool Aspose::Words::MailMerging::FieldMergingArgs::Is ( const System::TypeInfo target) const
overridevirtual

◆ set_Text()

void Aspose::Words::MailMerging::FieldMergingArgs::set_Text ( System::String  value)

◆ Type()

static const System::TypeInfo& Aspose::Words::MailMerging::FieldMergingArgs::Type ( )
static