Creating a Template

Creating a Merge Field

OfficeWriter's WordTemplate object opens a WordWriter template file, populates it with data from one or more data sources, and generates a new Word file.

A WordWriter template is a file created in Microsoft Word that contains merge fields. A merge field displays a data source field name (for example, a database column name) where a data source value will be inserted. Merge fields are bound to a data source in OfficeWriter code. When you run the code, OfficeWriter replaces the merge fields with values from the data source and creates a new Word file.

WordTemplate's SetDataSource method binds the merge fields to a data source, which may be an array or a database table record. The Process method enters values from the data source in the template's merge fields.

To create a merge field:

1. In Microsoft Word, open or create a document to use as your WordWriter template.
2. From the Insert menu, select Field... to open the Field dialog.
3. From the Field names list, select MergeField.
4. In the Field name text box, enter a name for the merge field. For example, enter ProductName.
5. Optional: From the Format list, select a display format.
6. Optional: In Field Options, check Text to be inserted before and enter text to insert before the merge field.
7. Optional: In Field Options, check Text to be inserted after and enter text to insert after the merge field.

The Field Dialog in Microsoft Word 2002 (XP)

Creating a Repeat Block

A repeat block is a text fragment, a list, or a table row in the template document, defined by a Word bookmark, that contains merge fields. In the WordWriter code, a data source is assigned to each repeat block. Repeat blocks allow you to:

• Assign multiple data sources to a single template, and
• Import multiple rows from a data source.

To create a repeat block:

1. In Microsoft Word, open or create a document to use as your WordWriter template.
2. Create a text fragment, a list, or a table row that contains merge fields. For example:
   
3. Select the text, list, or table row that you want to define as a repeat block. For example:
   
4. Open the Insert menu and select Bookmark... to open the Bookmark dialog.
5. Enter a bookmark name and click Add.

In Microsoft Word, bookmarks are not marked by default. To see which document fragments are bookmarks:

1. Open the Tools menu and select Options...
2. Select the View tab.
3. Under Show, check Bookmarks.

Bookmarks are marked by grey brackets:

Not all Word features can be included in a repeat block:

Creating a Mail Merge

A mail merge is a text fragment, a list, or a table row in the template document that contains merge fields. Unlike repeat blocks, a bookmark is not needed to define the fragment to be repeated. The entire page is treated as a repeat block and repeated as the document is filled with data. The NEXT field can optionally be used to tell WordWriter to move to the next row of data between identical merge fields. Mail merges allow you to import multiple rows from a data source without defining a repeat block.

To create a mail merge:

1. In Microsoft Word, open or create a document to use as your WordWriter template.
2. Create a text fragment, a list, or a table row that contains merge fields. For example:
   
3. Insert Next fields where you would like the data source to move to the next row when it hits a repeat of the same merge fields.

Not all Word features can be included in a Mail Merge:

Fast Save Word Files

WordWriter cannot process "fast saved" Word files. Fast saving is a Microsoft Word feature that makes file saving faster by saving only document modifications. When you create a WordWriter template, make sure that fast saves are turned off:

1. In Microsoft Word, open the Tools menu.
2. Select Options...
3. Select the Save tab.
4. Make sure that Allow fast saves is not checked.
   

Using an ODBC Data Source to Create Merge Fields

WordWriter populates merge fields with values from an array or a database. When you use a database as the template's data source, you can use Word's MailMerge toolbar to connect to the database, and select merge fields names from a list of available database fields:

1. In Microsoft Word, open or create a document to use as your WordWriter template.
2. From the View menu, select Toolbars -> Mail Merge.
3. Click the Open Data Source icon.
   
4. Select a database. For example, open the Access database Northwind.mdb, located in WordWriter\doc-samples\samples\database.
5. Select a database table from the list.
6. Click the Insert Merge Fields icon.
   
7. From the Fields list, select a field (a column name) and click Insert. Repeat to add additional fields to the template.
8. To format a merge field, right-click the merge field and select Edit field... to open the Field dialog. For more information about the Field dialog, see Creating a Merge Field.

Example: Creating an Envelope Template

The following VB.NET and C# samples use WordWriter to open an envelope template, set a data source, populate the merge fields, and generate a new envelope. The envelope template contains merge fields for the delivery name and address, and the return name and address. The WordWriter code uses an array as the data source and gets the array values from an HTML form. To run the sample, click Run Sample, enter return and delivery information in the form, and click the Generate button.

Code sample: Using an Envelope Template

[C#] | [VB.NET]
To create an envelope template:

1. Open Microsoft Word.
2. To display the Mail Merge toolbar, open the View menu and select Toolbars -> Mail Merge.
3. Click the Main document setup icon.
   
4. Select Envelopes.
   
5. In the Envelope Options dialog, select envelope size, address fonts, and printing options.
6. Enter merge fields in the envelope's delivery and return address boxes (within the main document). For instructions, see Creating a Merge Field.

Example: A Fax Cover Template

The following VB.NET and C# samples use WordWriter to open a fax cover template, set a data source, populate the merge fields, and generate a new fax cover document. The template contains the merge fields ToName, FromName, FaxNumber, PhoneNumber, Subject, PageCount, Comments, chkUrgent, chkReview, and chkComment. The WordWriter code uses an array as the data source and gets the array values from an HTML form.

Check boxes in the HTML form provide the values for chkUrgent, chkReview, and chkComment. If a box is checked, "X" will be entered in the data source value array and displayed in the generated file. If a box is not checked, an empty string will be entered in the value array and nothing will be displayed by the field name (for example, by "Urgent") in the generated file. To run the sample, click Run Sample, enter the fax information in the form, and click the Generate button.

Code sample: Using a Fax Coversheet Template

[C#] | [VB.NET]
To create a fax cover template using one of Microsoft Word's available templates:

1. In Microsoft Word, open the File menu, and select New...
2. From the New Document window, select General Templates...
3. In the Templates dialog, select the Letters & Faxes tab.
4. Select one of the available fax templates.
5. Insert merge fields in the template.

Example: A Form Letter Template

The following VB.NET and C# samples use WordWriter to open a template form letter, set a data source, populate the merge fields, and generate a new file. The template form letter contains merge fields for recipient name and address and author name and title. The WordWriter code uses an array as the data source and gets the array values from an HTML form. To run the sample, click Run Sample, enter recipient and author information in the form, and click the Generate button.

Code sample: Using a Form Letter Template

[C#] | [VB.NET]