Merge: Change Field Text/Read Field Text

Start the merge process:

The mail merge is started by the method

MergeText(const FieldName: string = ''; AllTexts: Boolean = FALSE).

Both parameters are optional. If you need to merge only the text the cursor is located in (header, footer ..) use procedure MergeActiveText;

Example:

MergeText('',true) - merge the fields in all areas, headers and footers

MergeText('A*', true) - merge the fields whith names starting with "A" in all areas, headers and footers

MergeText('A*', 'name', true) - merge the fields whith names starting with "A" and Source='name' in all areas, headers and footers

Important: If you need to print (or export to PDF) the text right after the merge process you need to call ReformatAll(false, true)!

Merge only in header or footer:

If you need to merge the fields ONLY in a header or footer text use the MailMerge procedure of any TWPRTFDataBlock.You will have to pass as callback the OnMailMergeGetText procedure described below. (Please read more in )

Example: merge fields only in all header texts:

for i:=0 to WPRichText1.HeaderFooter.Count-1 do

if (WPRichText1.HeaderFooter[i].Kind=wpIsHeader) and   // only header

  not (WPRichText1.HeaderFooter[i].IsEmpty) then      // and not empty

  WPRichText1.HeaderFooter[i].MergeText(

  WPRichText1,                     // object used as 'Sender', can be also datasource ...

  WPRichText1MailMergeGetText,     // event handler (see below)

  false,                           // readonly, we want to modify

  '', nil, nil );                  // optional to restrict merge range  

EVENT Handler to insert/read the data:

To use mail merge you need to add an event to the event handler OnMailMergeGetText.

The event receives the field name as parameter 'inspname'.

FAQ

In the simplest case the event handler can be

procedure TForm1.DoMailMergGetTexte(

       Sender: TObject; const inspname: string;

  Contents: TWPMMInsertTextContents);

begin

Contents.StringValue := 'This is a test';

end;

It is possible, for example, to use this field name to retrieve the text from a data set:

Contents.StringValue := DataSet.FieldByName(inspname).AsString;

You can also change the attribute of the inserted text using 'MergeAttr'.

   Contents.MergeAttr.SetColor(clRed);

The object 'MergeAttr' is initialized with the character properties of the start object of the mailmerge field. If you want to use the first character of the merged text (this is the visible field name or the field data) You can use this code in the the OnMailMergeGetText event:

Contents.MergeAttr.CharAttr :=

     Contents.MergePar.CharAttr[

        Contents.MergeParPos+1];

This code assigns the character attribute of the character which follows the the mergefield.

If you need to insert formatted text you can do so by assigning HTML or RTF to the property StringValue. In case the HTML or RTF cannot auto detected you can give WPTools a hint it using the flags mmMergeAsRTF, mmMergeAsHTML, and mmMergeAsWPTOOLS in Contents.Options.

If you merge in RTF text and the inserted text starts with a table you will see an empty line. This "empty" line is used to store the field marker which is not automatically deleted by the merge process. If it is not required to repeat the merge process or to read out modified text you can let the Merge procedure delete the field marker. Simply set the flag mmDeleteThisField in the property Contents.Options. This flag can be also very useful if the merged text contains field markers on its own which have to be processed in a second run!

Additional Information:

In WPTools 5 the selection and cursor is always moved o the current field. So it is also possible to modify the text at the cursor position directly in the OnMailMergeGetText event. This was strictly forbidden in WPTools 4, in V5 it can be used carefully:

Insert a picture:

img := TWPOImage.Create(WPRichText1);

img.LoadFromFile(picname);

WPRichText1.TextObjects.Insert(img)

Insert a table:

WPRichText1.ClearSelection(true);

WPRichText1.AddTable(2,2,true);

Insert formatted text

// Delete the current contents of the field

WPRichText1.ClearSelection(true);

// Get the field default character attributes in 'WritingMode'

WPRichText1.WritingAttr.CharAttr :=  Contents.MergeAttr.CharAttr;

// And add text with variations of the attributes

WPRichText1.WritingAttr.IncludeStyle(afsUnderline);

WPRichText1.WritingAttr.IncludeStyle(afsBold);

WPRichText1.InputString('81541');

WPRichText1.WritingAttr.ExcludeStyle(afsUnderline);

WPRichText1.InputString(' Munich');

Please note that fields are represented by start and end objects (cass TWPTextObj). This objects have several useful properties, including 'EmbeddedText' which can be used to read and write the text between the markers. So if you need to quickly update the field at the cursor position you can set FiedlAtCP.EmbeddedText := 'NewText';

The references to the field obejcts are available in the OnMailMergeGetText procedure:

Contents.StartInspObject and Contents.EndInspObject. Please do not mix up with CurrentTextObject, that is the reference of the first object inside the field. CurrentTxtObject is the reference of the first image object, that is the same as CurrentTextObject.ObjRef.