The MailMerge.MergeField event occurs during mail merge when a simple mail merge field is encountered in the document. This gives further control over the mail merge and you can perform any actions when the event occurs. Use the MergeFieldEventHandler delegate to reference the method that will handle MergeField. This method should accept a MergeFieldEventArgs object that provides data for the MergeField event.
Example MailMergeAlternatingRows
Demonstrates how to implement custom logic in the MergeField event to apply cell formatting.
[C#]
public void MailMergeAlternatingRows()
{
Document doc = new Document(MyDir + "MailMerge.AlternatingRows.doc");
// Add a hadler for the MergeField event.
doc.MailMerge.MergeField += new MergeFieldEventHandler(HandleMergeFieldAlternatingRows);
mBuilder = new DocumentBuilder(doc);
mRowIdx = 0;
// Execute mail merge with regions.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
doc.Save(MyDir + "MailMerge.AlternatingRows Out.doc");
}
private DocumentBuilder mBuilder;
private int mRowIdx;
/// <summary>
/// Called for every merge field encountered in the document.
/// We can either return some data to the mail merge engine or do something
/// else with the document. In this case we modify cell formatting.
/// </summary>
private void HandleMergeFieldAlternatingRows(object sender, MergeFieldEventArgs e)
{
// This way we catch the beginning of a new row.
if (e.FieldName.Equals("CompanyName"))
{
// Select the color depending on whether the row number is even or odd.
Color rowColor;
if (IsOdd(mRowIdx))
rowColor = Color.Azure;
else
rowColor = Color.BlanchedAlmond;
// There is no way to set cell properties for the whole row at the moment,
// so we have to iterate over all cells in the row.
for (int colIdx = 0; colIdx < 4; colIdx++)
{
mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
}
mRowIdx++;
}
}
/// <summary>
/// Returns true if the value is odd; false if the value is even.
/// </summary>
private static bool IsOdd(int value)
{
// The code is a bit complex, but otherwise automatic conversion to VB does not work.
return ((value / 2) * 2).Equals(value);
}
/// <summary>
/// Create DataTable and fill it with data.
/// In real life this DataTable should be filled from a database.
/// </summary>
private static DataTable GetSuppliersDataTable()
{
DataTable dataTable = new DataTable("Suppliers");
dataTable.Columns.Add("CompanyName");
dataTable.Columns.Add("ContactName");
for (int i = 0; i < 10; i++)
{
DataRow datarow = dataTable.NewRow();
dataTable.Rows.Add(datarow);
datarow[0] = "Company " + i.ToString();
datarow[1] = "Contact " + i.ToString();
}
return dataTable;
}
[Visual Basic]
<Test> _
Public Sub MailMergeAlternatingRows()
Dim doc As Document = New Document(MyDir & "MailMerge.AlternatingRows.doc")
' Add a hadler for the MergeField event.
AddHandler doc.MailMerge.MergeField, AddressOf HandleMergeFieldAlternatingRows
mBuilder = New DocumentBuilder(doc)
mRowIdx = 0
' Execute mail merge with regions.
Dim dataTable As DataTable = GetSuppliersDataTable()
doc.MailMerge.ExecuteWithRegions(dataTable)
doc.Save(MyDir & "MailMerge.AlternatingRows Out.doc")
End Sub
Private mBuilder As DocumentBuilder
Private mRowIdx As Integer
''' <summary>
''' Called for every merge field encountered in the document.
''' We can either return some data to the mail merge engine or do something
''' else with the document. In this case we modify cell formatting.
''' </summary>
Private Sub HandleMergeFieldAlternatingRows(ByVal sender As Object, ByVal e As MergeFieldEventArgs)
' This way we catch the beginning of a new row.
If e.FieldName.Equals("CompanyName") Then
' Select the color depending on whether the row number is even or odd.
Dim rowColor As Color
If IsOdd(mRowIdx) Then
rowColor = Color.Azure
Else
rowColor = Color.BlanchedAlmond
End If
' There is no way to set cell properties for the whole row at the moment,
' so we have to iterate over all cells in the row.
For colIdx As Integer = 0 To 3
mBuilder.MoveToCell(0, mRowIdx, colIdx, 0)
mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor
Next colIdx
mRowIdx += 1
End If
End Sub
''' <summary>
''' Returns true if the value is odd; false if the value is even.
''' </summary>
Private Shared Function IsOdd(ByVal value As Integer) As Boolean
' The code is a bit complex, but otherwise automatic conversion to VB does not work.
Return ((value / 2) * 2).Equals(value)
End Function
''' <summary>
''' Create DataTable and fill it with data.
''' In real life this DataTable should be filled from a database.
''' </summary>
Private Shared Function GetSuppliersDataTable() As DataTable
Dim dataTable As DataTable = New DataTable("Suppliers")
dataTable.Columns.Add("CompanyName")
dataTable.Columns.Add("ContactName")
For i As Integer = 0 To 9
Dim datarow As DataRow = dataTable.NewRow()
dataTable.Rows.Add(datarow)
datarow(0) = "Company " & i.ToString()
datarow(1) = "Contact " & i.ToString()
Next i
Return dataTable
End Function
[Java]
public void MailMergeAlternatingRows() throws Exception
{
Document doc = new Document(getMyDir() + "MailMerge.AlternatingRows.doc");
// Add a hadler for the MergeField event.
doc.getMailMerge().addMergeFieldEventHandler(new HandleMergeFieldAlternatingRows());
mBuilder = new DocumentBuilder(doc);
mRowIdx = 0;
// Execute mail merge with regions.
SuppliersDataTable dataTable = GetSuppliersDataTable();
doc.getMailMerge().executeWithRegions(dataTable);
doc.save(getMyDir() + "MailMerge.AlternatingRows Out.doc");
}
private DocumentBuilder mBuilder;
private int mRowIdx;
/// <summary>
/// Called for every merge field encountered in the document.
/// We can either return some data to the mail merge engine or do something
/// else with the document. In this case we modify cell formatting.
/// </summary>
private class HandleMergeFieldAlternatingRows implements MergeFieldEventHandler
{
public void mergeField(Object sender, MergeFieldEventArgs e) throws Exception
{
// This way we catch the beginning of a new row.
if ("CompanyName".equals(e.getFieldName()))
{
// Select the color depending on whether the row number is even or odd.
Color rowColor;
if (IsOdd(mRowIdx))
rowColor = Color.LIGHT_GRAY;
else
rowColor = Color.YELLOW;
// There is no way to set cell properties for the whole row at the moment,
// so we have to iterate over all cells in the row.
for (int colIdx = 0; colIdx < 4; colIdx++)
{
mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
}
mRowIdx++;
}
}
}
/// <summary>
/// Returns true if the value is odd; false if the value is even.
/// </summary>
private static Boolean IsOdd(int value)
{
// The code is a bit complex, but otherwise automatic conversion to VB does not work.
return ((value / 2) * 2) == value;
}
/// <summary>
/// Create DataTable and fill it with data.
/// In real life this DataTable should be filled from a database.
/// </summary>
private SuppliersDataTable GetSuppliersDataTable()
{
ArrayList data = new ArrayList();
for (int i = 0; i < 10; i++)
data.add(new Supplier("Company " + i, "Contact " + i));
return new SuppliersDataTable(data);
}