Home » Newsletter » September 2007

Implementing Mail Merge In Electronic Document Creation

Using custom placeholders in strings written to documents

By R. Vyshakh and D. Ashwini

For this month's article on eDocEngine VCL, we will see how to load a list of mail-merge variables from a CSV (comma-separated values) file and then dynamically write them to documents at run time. The source code presented here will use the PDF engine (TgtPDFEngine).

First, you create a string list and load the values from the CSV.

CurrRec: Integer;
CustomerList: TStringList;

...
// Load mail-merge variables from a CSV into a list
CustomerList := TStringList.Create;
...
CustomerList.LoadFromFile('CustomerList.csv');

To ensure that custom placeholders in strings are translated at run-time, you need to set the TgtPDFEngine.Preferences.CalculateVariables property to true. You can then text out strings with custom variables. You need to mark the placeholders with the delimiters <% and %>.

with gtPDFEngine1 do
begin
 ...
 // Enable translation of custom placeholders
 Preferences.CalculateVariables := True;
 ...

 for LI := 0 to CustomerList.Count - 1 do
 begin
   BeginDoc;
   TextOut(0, 0.25, 'Date: ');
   TextOut(0.75, 0.25, CphShortDate );

   TextOut(0, 0.5, 'Address:');
   // Write strings with custom placeholders
   TextOut(0.75, 0.5, '<%CustomerAddress%>');

   TextOut(0, 1.25, 'Dear <%CustomerName%>,');

   TextOut(0, 0.75, 'E-Mail:');
   TextOut(0.75, 0.75, '<%CustomerE-mail%>');
   ...
   EndDoc;
   CurrRec := LI;
 end;
end;

Next, you need to handle the OnCalcVariables event of the PDF engine so that at run-time you are able to supply the mail-merge variables from the string list.

procedure TForm1.gtPDFEngine1CalcVariables(
    Sender: TgtCustomDocumentEngine;
    Variable: String; var Value: String);
var
  LTemp: TStringList;
begin
  LTemp := TStringList.Create;
  try
    LTemp.CommaText := CustomerList[CurrRec];
    // Provide relevant values from the string list 
    // for custom placeholders 
    if Variable = 'CustomerName' then
      Value := LTemp[0]
    else if  Variable = 'CustomerAddress' then
      Value := LTemp[1]
    else if Variable = 'CustomerE-mail' then
      Value := LTemp[2];
  finally
    LTemp.Free;
  end;
end;

---o0O0o---

Downloads:

Zipped project file plus executable and sample CSV.

This site is best viewed on a screen with minimum resolution of 1152 x 864 pixels. Windows users are advised to use Microsoft ClearType Tuning for optimal experience. Linux and other users can enable font smoothing, as supported by their OS. Also, please use the latest version of a standards-compliant browser such as Opera, FireFox, Chrome or Safari.