Implementing a MERGEFIELD Class

Windows Forms User's Guide > Howto: Use Text Fields

The MS Word MergeField is the most commonly used field in MS Word and RTF documents. It enables template designers to add additional information to a text field, such as a specific text that should be displayed before or after the field text or the format of the text.

To handle these fields and it's functionality, this sample implements three different classes:

The MergeField class is inherited from the TextField base class and extends it's functionality to cover all properties of a MergeField. This MergeField gets a reference to the ApplicationField that will be manipulated by the class. Additionally, a MergeField contains the following parameters that are implemented through it's properties:

If the TextBefore property of the MergeField is set, the Text property of this inherited class manipulates the referenced ApplicationField instance and it's Text. Additionally, this new setting is saved in the Parameters property in the appropriate format.

The MergeFieldCollection is the collection for the MergeField instances. It implements all common properties and methods of standard collection.

Finally, a synchronization object is required to synchronize the existing collections of a TextControl instance and the new MergeFieldCollection. It must be synchronized every time the ApplicationField collection is changed. This class attaches two important events to the parent TextControl class that listens for changes in this collection: TextFieldCreated and TextFieldDeleted.

After starting the sample, click on File / Load to load a sample document, which contains several merge fields. Set the input position inside an exsiting field, for sample <<COMPANY>>.

Open the implemented merge field dialog by choosing Edit... from the MergeField main menu.

Using this dialog, it is possible to manipulate all properties of the MergeField instance. Add some text that should be inserted after the field by checking the checkbox Text to be inserted after. Type some text in the appropriate text box and close the dialog by clicking OK.

Open the customer data grid form by clicking Merge fields... from the Merge menu entry. Choose a customer by clicking on a specific row and click Merge to merge all merge fields with the database content.

In this process, the MergeFieldCollection is used to loop through all inserted fields to replace the text. The following code shows this loop:

DataGridViewRow curRow = dataGridView1.SelectedRows[0];
foreach (MergeField curMergeField in m_mergeFieldCollection)
    foreach (DataGridViewTextBoxCell curCell in curRow.Cells)
        if (curCell.OwningColumn.Name == curMergeField.MergeFieldName)
          curMergeField.Text = curCell.Value.ToString();
[Visual Basic]
Dim CurRow As DataGridViewRow = DataGridView1.SelectedRows(0)
For Each CurMergeField As MergeField In m_MergeFieldCollection
    For Each CurCell As DataGridViewTextBoxCell In CurRow.Cells
        If CurCell.OwningColumn.Name = CurMergeField.MergeFieldName then
            CurMergeField.Text = CurCell.Value.ToString()
        End if