Mail Merge Templates v1.3 - J&S Software

by Tom Hebenstreit, Review Editor

Published 1997-11-01    Printer-friendly version

Mail merge (the process of combining unique data with repetitive text) is one of those common business needs that can be used in virtually any kind of application where your users need to communicate with other people. Prior to the release of the J & S Mail Merge templates, you really only had two choices if you wanted to merge your data files with user created documents - do it all yourself or purchase a product to help you integrate your application with an external program like Microsoft Word. The first is very time consuming, and the second option involves a sometimes volatile soup of OLE, DDE and WordBasic macros, not to mention that new versions of Word are as likely as not to break your system.

So wouldn't it be better if you could just do it all within your own application, easily, quickly and with an amazing amount of flexibility? Never fear, people, J & S is here with a well-rounded, easily implemented set of Mail Merge templates and utilities that will let you add powerful Mail Merge capabilities to your apps in record time...

How does it work?

The basic concept of the templates is that you have one or more special files which contain 'tokens' - unique identifiers which are placed in your documents or memos as placeholders for information which is not yet available. Tokens are distinguished from the surrounding text by their 'delimiters' - a set of surrounding characters that tell the template functions "I am a token, replace me with something else". In the Mail Merge Templates, the standard delimiters for tokens are '((--' and '--))', with the name of the token placed between the delimiters like this: ((--MyToken--)). The token files have an extension of MRG, as in MYTOKENS.MRG, though they are actually standard TopSpeed (TPS) files under the covers. You can have multiple MRG files, and use filters within those files to select specific sets of tokens for display/selection.

How does the system work? Simply put, in a memo (letter) to be mail merged you might place a token called, for example, '((--Company--))' which represents the company name field from a customer file. Whenever the document is merged (for printing, e-mailing or whatever), the templates look up each token in a MRG file, then replace it with whatever is specified in the MRG file (in this case, it says to replace the token with the company name field from the current customer record). Other tokens might represent addresses, names, or any other data field from your dictionary. For every record processed, its data is merged into the same basic letter giving the appearance that the letter was created for that individual company alone.

Where these templates really begin to shine, however, is in the fact that data fields are only the beginning: A token can also represent constant text or virtually any Clarion run-time expression, including functions of your own! You (or your users) can easily define a token called, say, ((--CityStateZip--)) which has as its 'value' standard Clarion code to combine three file fields like this:

clip(cus:city) & ', ' & upper(cus:state) & ' ' & cus:zip

Anywhere this token is inserted, the result will be a nicely formatted string looking something like 'Los Angeles, CA 90230'. Multi-line headers, signature lines, blocks of constant text, even lists of data from other files, can all be represented by simple merge tokens. Best of all, it is all available at run-time. You (or your users, if you let them), can create, modify, remove, and merge tokens and token files without requiring any changes to your program, even though those tokens contain actual Clarion code.

This is powerful stuff, and the uses to which it can be put are basically limited only by your imagination.

Major Features

The Mail Merge templates include the following outstanding features:

• Simple implementation of Mail Merge functionality in your apps.
• Tools to automate and simplify the creation of MRG files (files of tokens). You can also import and export sets of tokens between files and print out lists of tokens.
• Libs and DLLs that provide all of the basic procedures required to easily create, insert and merge tokens without any coding on your part.
• Templates to integrate the merge process with Report and Process procedures, as well as control and code templates to call the pre-written functions in the Libs and DLLs.
• Source Apps for the pre-written functions and procedures that interact with the user, so that you can modify them to match your own look and feel if needed.
• Allows the user to create and maintain their own custom tokens, as well as giving you the capability to specify certain tokens (or token files) as developer only so that only you can change them.
• Tokens can contain text, data fields or standard Clarion code that is evaluated dynamically at run-time.
• Within the limits CW imposes on 'bound' functions, you can write functions of your own which can be used in tokens just like standard Clarion functions.
• For non-English users (or for simple modification of the prompts, tool tips, etc., in the supplied DLLs), a special function can be used to create an INI file with the alternate information.
• Includes extensive support for the X-Gen RichX Word Processing product.
  [Note: See the October issue of Clarion Online for a complete review of RichX]

To summarize, enough templates and tools are provided to enable you to implement Mail Merge capabilities in your apps with little or no embedded hand code, while still providing full access to the functions if you do wish to use them in hand code.

Installation

The templates are provided in a professional single file install program (no unzipping or similar hassles required). After running the install program and entering a password, you are asked where the templates should be installed. I was most pleasantly surprised to see that it had already located the CW20 directory on my E: and selected it as the destination, rather than the usual practice of just defaulting to C:\CW20 like many other programs.

Two install options are provided, one for the templates and support apps, and one for the Mail Merge demo program. I highly recommend that you install the demo program, as it provides a wealth of information about using the product (more on the demo later). After a final confirmation, the templates are installed and the Help file automatically displayed so that you can get acquainted with the ins and outs of your spiffy new tool.

Once you exit the Help file, you will find two new directories under your \CW20 directory - one for the demo and other support apps - and one that contains the source apps for the DLLs used by the templates. All other templates, help files, Libs and DLLs are installed properly in their respective CW directories (templates in \CW20\Templates, etc.) and are ready to go.

As usual, you have to register the templates before they can be used (before you can run the demo, either).

In the unlikely event that you wish to remove the Mail Merge Templates, an uninstall program is also provided.

Demo wows and woes

On the bright side

The demo program which accompanies the templates is well done, with lots of on-screen explanations to help guide your actions or describe what is going on. It covers all of the basic functions of the templates as well as some advanced capabilities like binding a function and using it (with a single token) to provide a list of related records from another file (a list of invoices for a customer, in this case).

The MRG token file for the demo is preloaded with a variety of tokens, from simple field substitutions to multi-line, multi-field tokens. The memo edit screens demonstrate how to insert tokens and also let you preview the results of a merge immediately, making it easy to experiment with tokens and learn how they function. You can also create your own tokens on the spot, insert them and preview them right away as well. As I said, great for getting a handle on how the Mail Merge system actually works.

The demo also demonstrates the template's extensive support for X-Gen's powerful RichX word processor, and therein lies a fly in the ointment if you don't happen to own RichX... (Note: If you do own RichX, you won't have any problems with the demo.)

On the dark side

The Mail Merge demo is provided as an App file, and if you don't happen to own RichX, you will see a series of RichX template errors when you load the app. You will not be able to compile it, either, as the missing RichX templates will cause a ton of error messages. You can still examine how it is all put together, but that is not the same as seeing it all in action and experimenting with the tokens interactively. At this point, your options are:

• Download the precompiled demo from Compuserve or the J&S web site (about 850k) and experiment with that. It will automatically detect if RichX is installed and modify its behavior accordingly.
• Delete all of the procedures related to RichX and compile the demo without them.
• Download the 30-day trial version of RichX (around 6 megs) from the X-Gen web site (www.x-gen.com), install it and then load and compile the demo.

All in all, a lot more effort than it should take just to run the demo. I would suggest that J&S provide two demo apps with the templates - one for use with stock CW and one for RichX owners.

Adding the Templates to your app

Once I had thoroughly explored the demo by running it and inspecting the app file itself, it was time to take the plunge and put the templates to work in an app of my own.

I selected an older app of mine which already had rudimentary mail merge capabilities, implemented as follows: memos which contained letter body text were merged into reports which had the individual file fields such as addressee, date, etc., hard coded into the headers and footers of the report. Any changes to the basic layout of individual reports/letters other than simple changes to the memo body text required a recompilation of the entire program (yechh!). This type of application seemed tailor made to take advantage of the dynamic capabilities of these templates...

So, as laid out in the Help file, here are the five basic steps (with a few side trips) to mail merge nirvana:

1. Open your app and add the Mail Merge Global Extension.
2. Use the provided Utility Template to create a file of fields from your Dictionary (it will be used to load an MRG token file). Options are provided to skip fields marked in the Dictionary as 'No Populate' and to specify which files you wish to export. An option is also provided to export all of the files with a single checkbox. As a bonus, you can also use a special flag ('JSNOMERGE ') in the User Options of both files AND fields in your dictionary to specify files or individual fields that should not be exported.
   
   Note: As with many aspects of CW, some time spent in your dictionary before using this template will ensure that you get exactly the results you want when creating the exported fields file.
3. Now that the fields are out of your dictionary, they need to be turned into an MRG file (a token file, as described above). One "gotcha" which was not described in the help file was that the program which loads the fields (called 'MergEdit') is provided only as an App file, so you now need to exit your app and load/compile/run the MergEdit.App before you can proceed.
   
   Once you have MergEdit running, you can then load your fields into a MRG file, specify the default token delimiters, add new tokens for common computed values (such as today()), set flags as to who can change tokens, and basically massage the MRG file into final form. Note that you can run MergEdit any time you want, and even incorporate its functionality into your own apps with a supplied template.
4. OK, we have a MRG file full of tokens, now what? Well, back to your app, choose a Form that has a memo containing stock letter text, then add a Mail Merge Insert Token control template and fill in a few prompts. This adds an 'Insert Token' button which handles all of the details relating to adding tokens to the memo text, from popping up the list of available tokens to inserting the selected token into the text at the current cursor location. That was easy, wasn't it?
5. Next up is to add the Mail Merge Extension to a Report, so that you can print out merged letters, thus completing the process. Note that a Mail Merge report can be basically just a single detail filled with one memo field. The memo contains the full text of the letter from headers to signature lines. In my test app, one report now replaced more than a half dozen of the older hard coded reports, yet offered magnitudes more flexibility for end user layout and control.

That was it. Pretty much a point and click pass through the supplied utilities and my application that took less than 30 minutes. Mind you, this application already had the basic concepts for mail merge implemented in it (letter text in memo files, browses to select which memo/letter to use, etc.) so your mileage will vary. The process of implementing the templates, however, was straightforward and as easy as this kind of task can ever be.

Mail Merge in action

Using my new modified app, I created new letters, inserted tokens and ran my new report to view the results. The more I played (er... worked) with it, trying various functions and expressions in my tokens, the more impressed I was with the flexibility of the system.

update screen)

Forging on, I added the capability to preview memos/letters as I was creating them by following (OK, copying) less than a dozen lines of embed code and a view window procedure from the demo app to the update Form in my app where I had added the 'Insert Token' button. Even more fun, as I could now modify letter text, insert tokens (or create and/or modify tokens on the fly before inserting them) and then preview the results immediately from the same update form. This is wonderful for debugging your tokens.

background)

In addition to the simple report/letter mail merge outlined above, I also experimented with using the templates to generate personalized e-mail messages using a Process and Stealth Software's Mail/Fax templates. This required more hand code, but it worked great, once again allowing me to move the majority of the text from the app to the memos and token files, and letting me use one procedure for any number of dynamic messages.

Finally, I also downloaded and installed the demo version of RichX so that I could try out the RichX support. I didn't try implementing both RichX and the J & S templates in my own application, but they worked together as expected in the J & S demo app and are a very (and I mean VERY) impressive combination. (So who needs MS Word, anyway?)

Nobody's perfect...

Note, though, that there are some limitations to what you can do. One of the primary limitations is simply that you cannot use multiple fonts when printing merged documents. This is not a Mail Merge Templates problem per se, but rather a limitation in the way CW prints memos. (Did I hear someone say... RichX?) Another is that tokens are not protected within your letters, i.e., they can be inadvertently altered by the user: ((--Today--)) could be changed to ((--Today-), in which case it will simply print as is rather than being recognized as a token. This is easily fixed, though, by correcting or re-inserting the token. (Note: RichX does protect tokens.)

Large MRG files can slow performance, and getting functions and variables bound correctly can be stress-provoking at times. You can nest tokens within other tokens, but the process of getting them all evaluated correctly is somewhat haphazard and requires hand-code and repeated calls to the merge functions.

There are a few CW quirks which J & S documents as well, including CW functions which don't work as expected or generate errors (like @P###P picture tokens). To get around some of them, J & S provides their own function called JS_Fformat(), which substitutes for the CW Format() function in those special cases. Another documented problem occurs with certain combinations of single quotes within other single quotes - these can result in difficult to track down GPF's. They recommend avoiding the use of single quotes within token text, but that isn't always possible in the real world where users are allowed to create their own tokens and put whatever text they want in them.

I also discovered a situation where a bound function used in a token would fail and return an error message instead of the desired text under a few circumstances (if there were no data in a file it was reading, for example). The problem is hard to trace, though, and I am still trying to determine where the problem really lies (CW, Mail Merge or me) with the assistance of J & S.

Documentation

This is probably the weakest aspect of the templates, as no printed or printable documentation is provided. All instructions and information reside in a standard Windows Help file, which leads to a sometimes frustrating click-a-thon as you search through the file for a specific piece of information.

On the plus side, the individual functions and templates are well documented with screen shots and example code once you find them. As mentioned earlier, the demo is also an excellent source of information.

Technical Support

Support for the templates was very good, with all technical questions answered promptly via e-mail (usually within two hours, and often a lot less). I have to admit, though, that I was hard pressed to come up with many questions, since the templates were so easy to install, implement and use.

Summary

All in all, J & S Mail Merge is a very flexible, high-quality product that defines its niche and then fills it admirably. On top of that, the more I worked with it the more possibilities I saw for using this style of dynamically processed run-time code outside of the usual confines of printed report and e-mail merges. If a few of the edges were polished just a bit more, I'd probably have to rate the product's ability to do the task as that rarest of honors - Excellent. As it was, it is close...

So what would I like to see in future versions? Really just two things (for now) - the ability to limit displayed tokens so that you can present the user with only those choices which are relevant to the current action; and the ability to have nested merge tokens inside a conditional token evaluated in one pass. (Don't ask for much, do I?)

In any case, if your apps require any kind of dynamic text merging technology, you owe to yourself (and your users) to download the demo and check it out.

Category	Product Score
Ability to do the task	Very Good
Ease of use	Very Good
Ease of Installation	Excellent
Documentation	Good
Technical Support	Excellent
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	Yes*

* Note: Source code for the core functions which do the actual merging of tokens is not available; however, apps are provided for all of the other parts of the system, including all procedures and functions which display a window or interact with users.

The J & S Mail Merge Templates list for $129 US and can be ordered via:

TopSpeed Corporation Sales - 1-800-354-5444

Compuserve SWREG #14400 (cost: $139 due to CSi overhead charges)

J & S Software - www.jssoftware.com or contact Jeff@jssoftware.com

The full demo is available for download at the above web site as well.

Review comments from Jeff Slarve, J&S Software Co.

Regarding the comments on the sample application: Thank you very much for pointing out what now seems like the obvious. In future install files, we will be including sample applications for both RichX and non-RichX. I can see how that would be an immediate inconvenience for those that don't yet have access to RichX. The "Mergedit.exe" omission: Actually, MERGEDIT.EXE is installed in the \cw20\bin directory by the setup program. That way, it can be executed via the command line from wherever your applications reside. I guess the real omission was mentioning this in the help file. Thank you for pointing this out. The documentation: I can see how a "clickathon" <g> could get a little bothersome, and will try to improve the layout and consistency of the help file. I think the biggest part of this is the index, which we will improve upon. The suggestions: The situation-specific filters idea is an excellent suggestion. I don't know why I didn't think of it myself. This will definitely be something we will be adding in the future. The nested-tokens idea is also very good. There are many ways which we could approach this, and I will put some thought into it.

Printer-friendly version

Copyright © 1999-2009 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942