Introduction:
"Mail-merge" means the automatic update of data fields in any document.
It can be used to do mass mailing or to create customizable database record views.
This is done by once procedure, MergeText and the event OnMailMergeGetText. If you have a text with fields marked with special characters (<name>) use method ReplaceTokens. Otherwise crate fields with method InputMergeField. Note, that mail merge fields are embedded into two instances of the TWPTextObj class. This FAQ shows how to work with images. Note: If you need to print (or export to PDF) the text right after the merge process you need to call ReformatAll(false, true)!
Concept of mail-merge in WPTools:
The text contains merge fields, on command "MergeText" the component locates all fields and triggers the event OnMailMergeGetText for each of it. This event is used to fill data into the field or read out the current contents. Please note, that this concept differs from the usual "search and replace" and is much more verstile and faster. With WPTools merge fields are not destroyed by the merge process, the field data can be exchanged as soon as it changes. So it is possible to scroll through a database with a merge letter being "attached". It is also possible to read out the contents of the merge field. So the document can be also used as data entry from. You can merge in standard ANSI text, formatted text and images. Formatted text may be encoded in HTML, RTF or the WPTOOLS format.
Info: Mail merge templates can be converted to reporting templates which use the WPTools WPReporter addon.
Note: Inside the event OnMailMergeGetText the text in the source editor is selected. This means all interfaces and methods which work on selected text will actually read and modify the text inside the field. So, instead of using Contents, You can also clearing the text by a call to TWPCustomRTFEdit(Sender).ClearSelection or you change its attribute. You can also use InputString or TableAdd.
Also see: extended mail-merge technique.
Three steps to create a working prototype of mail-merge in Your application:
1) Add code to create a field (more...)
procedure TForm1.Button1Click(Sender: TObject);
begin
WPRichText1.InputMergeField('NAME','Default-Name');
end;
2) Provide an event handler for the event OnMailMergGetText (more...)
In the created handler please type some lines of code
procedure TForm1.WPRichText1MailMergeGetText(Sender: TObject;
const inspname: String; Contents: TWPMMInsertTextContents);
begin
if inspname='NAME' then
Contents.StringValue := 'Julian Ziersch'
else Contents.StringValue := '<unknown>';
end;
3) Launch mail merge with a different button (more...)
procedure TForm1.Button2Click(Sender: TObject);
begin
WPRichText1.MergeText;
end;
Instead of using fields, mail merge can also be performed on book marked text.
To do so, the MergeText method has to be called slightly differently.
WPRichText1.MergeTextEx( '', '', wpobjBookmark, [wpmergeAllTexts] )
Demo Projects
Please check out the ThreadSave demo to learn how to use mail merge in a thread.
Demos\I) MailMerge\MailM4 shows how to work with a database and merge multiple records:
Demos\I) MailMerge\ModifyTextInMailM shows how to separate the data from the mailmerge code, how to change attributes of the fields (or bookmarks) and how to insert a table inside the event.