ImageFieldMergingArgs Class

Provides data for the ImageFieldMerging(ImageFieldMergingArgs) event.

ExpandedInheritance Hierarchy

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

ExpandedSyntax

public class ImageFieldMergingArgs : FieldMergingArgsBase

The ImageFieldMergingArgs type exposes the following members.

ExpandedProperties

  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 exampleImage
Specifies the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageFileName
Sets the file name of the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageHeight
Specifies the image height for the image to insert into the document.
Public propertyCode exampleImageStream
Specifies the stream for the mail merge engine to read an image from.
Public propertyCode exampleImageWidth
Specifies the image width for the image to insert into the document.
Public propertyCode exampleRecordIndex
Gets the zero based index of the record that is being merged.
(Inherited from FieldMergingArgsBase.)
Public propertyShape
Specifies the shape that the mail merge engine must insert into the document.
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.)

ExpandedMethods

  NameDescription
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)

ExpandedRemarks

This event occurs during mail merge when an image mail merge field is encountered in the document. You can respond to this event to return a file name, stream, or an Image object to the mail merge engine so it is inserted into the document.

There are three properties available ImageFileName, ImageStream and Image to specify where the image must be taken from. Set only one of these properties.

To insert an image mail merge field into a document in Word, select Insert/Field command, then select MergeField and type Image:MyFieldName.

ExpandedExamples

Shows how to insert images stored in a database BLOB field into a report.
public void ImageFromBlob()
{
    Document doc = new Document(MyDir + "Mail merge destination - Northwind employees.docx");

    doc.MailMerge.FieldMergingCallback = new HandleMergeImageFieldFromBlob();

    string connString = $"Provider=Microsoft.Jet.OLEDB.4.0;Data Source={DatabaseDir + "Northwind.mdb"};";
    string query = "SELECT FirstName, LastName, Title, Address, City, Region, Country, PhotoBLOB FROM Employees";

    using (OleDbConnection conn = new OleDbConnection(connString))
    {
        conn.Open();

        // Open the data reader, which needs to be in a mode that reads all records at once.
        OleDbCommand cmd = new OleDbCommand(query, conn);
        IDataReader dataReader = cmd.ExecuteReader();

        doc.MailMerge.ExecuteWithRegions(dataReader, "Employees");
    }

    doc.Save(ArtifactsDir + "MailMergeEvent.ImageFromBlob.docx");
}

private class HandleMergeImageFieldFromBlob : IFieldMergingCallback
{
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        // Do nothing.
    }

    /// <summary>
    /// This is called when a mail merge encounters a MERGEFIELD in the document with an "Image:" tag in its name.
    /// </summary>
    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs e)
    {
        MemoryStream imageStream = new MemoryStream((byte[])e.FieldValue);
        e.ImageStream = imageStream;
    }
}
Shows how to set the dimensions of images as MERGEFIELDS accepts them during a mail merge.
public void MergeFieldImageDimension()
{
    Document doc = new Document();

    // Insert a MERGEFIELD that will accept images from a source during a mail merge. Use the field code to reference
    // a column in the data source containing local system filenames of images we wish to use in the mail merge.
    DocumentBuilder builder = new DocumentBuilder(doc);
    FieldMergeField field = (FieldMergeField)builder.InsertField("MERGEFIELD Image:ImageColumn");

    // The data source should have such a column named "ImageColumn".
    Assert.AreEqual("Image:ImageColumn", field.FieldName);

    // Create a suitable data source.
    DataTable dataTable = new DataTable("Images");
    dataTable.Columns.Add(new DataColumn("ImageColumn"));
    dataTable.Rows.Add(ImageDir + "Logo.jpg");
    dataTable.Rows.Add(ImageDir + "Transparent background logo.png");
    dataTable.Rows.Add(ImageDir + "Enhanced Windows MetaFile.emf");

    // Configure a callback to modify the sizes of images at merge time, then execute the mail merge.
    doc.MailMerge.FieldMergingCallback = new MergedImageResizer(200, 200, MergeFieldImageDimensionUnit.Point);
    doc.MailMerge.Execute(dataTable);

    doc.UpdateFields();
    doc.Save(ArtifactsDir + "Field.MERGEFIELD.ImageDimension.docx");
}

/// <summary>
/// Sets the size of all mail merged images to one defined width and height.
/// </summary>
private class MergedImageResizer : IFieldMergingCallback
{
    public MergedImageResizer(double imageWidth, double imageHeight, MergeFieldImageDimensionUnit unit)
    {
        mImageWidth = imageWidth;
        mImageHeight = imageHeight;
        mUnit = unit;
    }

    public void FieldMerging(FieldMergingArgs e)
    {
        throw new NotImplementedException();
    }

    public void ImageFieldMerging(ImageFieldMergingArgs args)
    {
        args.ImageFileName = args.FieldValue.ToString();
        args.ImageWidth = new MergeFieldImageDimension(mImageWidth, mUnit);
        args.ImageHeight = new MergeFieldImageDimension(mImageHeight, mUnit);

        Assert.AreEqual(mImageWidth, args.ImageWidth.Value);
        Assert.AreEqual(mUnit, args.ImageWidth.Unit);
        Assert.AreEqual(mImageHeight, args.ImageHeight.Value);
        Assert.AreEqual(mUnit, args.ImageHeight.Unit);
    }

    private readonly double mImageWidth;
    private readonly double mImageHeight;
    private readonly MergeFieldImageDimensionUnit mUnit;
}

ExpandedSee Also