Merge Documents

Merged documents result from combining information from a host or template document with information from a data document. The host document works like a template and can contain any kind of content just as any other Nisus Writer Pro document. The data document provides the detail that makes each merged document different. Its contents replace the “merge placeholders” in the host document. You combine one host document and one data document to generate many merged documents. Merging Documents

Here are some guidelines for merging documents:

Use the same merge placeholder names in both the host/template and the data documents.

Put the host and data documents in the same folder.

While this is not a requirement for merging the information it makes finding the appropriate data easier.

Make sure the host document is the top window before you start the merge.

The procedures that follow explain how to merge a host document (a form letter) with a data document (a list of people who should receive the letter).

Create a host document

The host document contains merge placeholders that are replaced with information from the data document.

Prepare the template document

It is often best to create a specific letter or document, and then convert it into a form letter afterward. For instance, you might want to send a letter like this:


Figure 496
A standard business letter

But you have several associates with whom you want to share this information. This is a perfect situation for doing a merge. Start with your letter to Reuben Simons, and alter it.

1. Choose commands of the menu Insert > Merge Placeholder to look something like this:


Figure 497
A standard business letter with Merge Placeholders

You will notice that not all the Merge Placeholders in the new letter appear in the menu Insert > Merge Placeholder. You can create any Merge Placeholder you want.

2. Choose the menu command: Insert > Merge Placeholder > Other… to enter custom placeholders and choose from the three available options.

Choose one of the commands from the Placeholder for Contacts property: pop-up menu (as illustrated at the top of Figure 498):
First Name, Middle Name, Last Name, Name Title, Name Suffix, Birthday, Email, Work Email, Home Email, Phone, Home Phone, Work Phone, Mobile Phone, Home FAX, Work FAX, Job Title, Department, Organization, Address, Address (city), Address (state), Address (zip), Address (country), Home Address, Home Address (city), Home Address (state), Home Address (zip), Home Address (country), Work Address, Work Address (city), Work Address (state), Work Address (zip), and Work Address (country).
These are the fields available in Apple's Contacts application.

Click Placeholder for the property with the name: and type the name of the placeholder you want to use in your document.

In addition you can check either or both:

▪︎ If not blank, then prepend: and add the text you want to have appear before the text that replaces the Merge Placeholder.

▪︎ If not blank, then append: and add the text you want to have appear after the text that replaces the Merge Placeholder.

Click Placeholder that uses the output from the following Perl code: and add your Perl code in the text box available in the dialog.

This code is run once for each record in the data document to derive the text used during merging (which should be printed to STDOUT or “standard output”). All data source property values are available to this block of Perl code in the special predefined “record” hash. A trivial example that constructs a full name:

print $record('First Name') . ' ' . $record('Last Name');


Figure 498
The “Other…” Merge Placeholder dialog

3. Click Insert.

If you use a placeholder from something other than the Contacts you would need to create a separate data document as explained in “About data documentsbelow.

This is your template document. The next step for you is to set up your data document.

About data documents

Here are some guidelines for creating data documents. Data documents are simply CSV, or Comma-separated values files. You can learn more about them here:


Enter the field names on the first line (paragraph) of the data document.

Enter the data field, the replacement text, in the same order as the field names to which they refer in the first line (paragraph).

You do not have to use brackets at all in data files.

Separate each field name and data field with a comma.

To include a comma in a field itself (for example, a date), enclose the whole field in straight quotes.

Nisus Writer Pro sees a comma as separating two fields. So if you put in December 25,1800 It would be seen as two fields, Dec 25 and 1800. Therefore, if you want it to have a comma, type it in straight quotes as "December 25, 1800".

To include quotes in a data document the following rule must be followed.

To include a straight double quote in a field value, you actually double-up the quote; you must enclose the entire value in straight double quote marks.

In order to achieve the result:
Arthur Herbert "the Fonz" Fonzarelli
using the Merge Placeholders «First Name» «Last Name» you need to have the following in the data document:
"Arthur Herbert "the Fonz"",Fonzarelli

Create a data document

1. Open a new, untitled file.

2. On the first paragraph of the file, type in the field names that you will be addressing in the file. For the case in our example, you would type in:

First Name, Last Name, Organization,Department,Address (street),Address (city),Address (state),Address (zip),feature

Leading and trailing spaces between the commas are ignored.

The sequence of the fields in the data document does not need to match their sequence in the template document (one field might be used multiple times).

3. On all subsequent lines of the file, enter the information for each unique letter in the same order as the field names on the top line. Remember to use a comma to separate each data field.

4. Choose the menu command: File > Save As….

5. Give the file a name that fits your project.

6. Choose Text from the File Format pop-up menu.

7. Click Save.

Saving the data document as Text.png

Figure 499
Saving the data document as Text

For the purpose of our example, the (fictional) text of the data file is:

Reuben,Simons,Loans and Acquisitions,Museum of Asian Art,198 South Bearing Way,San Francisco,CA,92999,floating graphics

Rea,D’ator,Publications,Museum of Asian Art (East Bay),9473 East Seaward Dr.,Oakland,CA,94736,comments

Minna,Hale,Chairwoman of the Board,Museum of Asian Art,3857 Ewinda Ave.,San Paolo,CA,93847,bookmarks and cross-references

Merge documents & display or print the results

Once you have your template/host document prepared and have your list of who you want to receive your letter ready you can merge the two sets of information.

Before you begin, be sure the template document is open.

Choose the menu command: from either

File > Merge Document… or 

Insert > Merge Placeholder.

A dialog box appears and asks you to specify:

what data you wish to use for the merge and

how you want the merged document to be created.

Decide the source of the data to be merged

The dialog opens ready for you to choose any record in your Apple macOS

The Merge Document dialog.01.png

Figure 500
The Merge Document dialog

Press and click to select a range of records or press to select (or remove from the selection) specific records.

If you have created a data document as explained in “About data documentsabove,

1. Click A text (CSV) file.

2. Click the Browse… button.

3. Navigate to your data document.

4. Click Open in the lower right corner of the Open dialog that appears.

Merging a document with a CSV (comma separated values) text file selected.png

Figure 501
Merging a document with a CSV (comma separated values) text file selected

Decide what to do with the new merged document

You can either save the merged file, print or display it. You might want to display it first to make sure the file looks as you expected.

Save the merged document to individual files

1. Click Saved individually to.

2. Click the Browse… button.

3. Navigate to the folder where you want the new files saved.

4. Click Open in the lower right corner of the Open dialog that appears.

Nisus Writer Pro offers to name the files according to a File name template consisting of the first name and the last name records of each new document. You can change that to anything you want.

Save the merged document to one file

1. Click Saved to one file.

2. Click the Browse… button.

3. Navigate to the folder where you want the new file saved.

Due to sandboxing, as a general rule, you cannot paste a file’s path into the field. However, Nisus Writer Pro might have access to the path for other reasons, including but not limited to:

You recently interacted with the file,

Nisus Writer Pro has access to any folder enclosing the file,

Some component of Nisus Writer Pro temporarily restored persisted access to any enclosing folder, such as: macros, document manager, etc.

4. Give the file a name.

Saving the merged document to one file with records divided by page breaks.png

Figure 502
Saving the merged document to one file with records divided by page breaks

5. Click Save in the lower right corner of the Save As dialog that appears.

Nisus Writer Pro offers to separate each portion of the new document.

6. From the Divide Records with pop-up menu choose one of the options:

Page Breaks

Section Breaks (Same Page)

Section Breaks (Next Page)

Print the merged document

Click Printed.

Nisus Writer Pro sends the merged documents directly to the printer.

See a preview of your merged document

Click Preview.

Nisus Writer Pro sends the first of the merged documents to the Preview application which opens the document as a graphic.

Previous Chapter
Use the Window menu and working with multiple windows
<<  index  >>
Next Chapter
Print Documents