Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Table of Contents

Merge Fields

Excerpt

A WordWriter template is a Microsoft Word file that contains merge fields. A merge field displays a data source field (for example, a database column name). A merge field is created in Microsoft Word and bound in code to a data source. The data source may be an array, a DataSet, a DataTable, or a DataReader. When you run the code, WordWriter populates the merge fields with data source values.

A template may contain multiple sets of merge fields. Each set of fields binds to a single data source. Implicitly or explicitly, a merge field always specifies both a data source and a column. For example, in the merge field*«Products.ProductID», "Products" is the data source and "ProductID" is the column. The merge field«ProductID»* refers to the "ProductId" column from the first data source defined in the WordWriter code.

...

Info

The Main Document and Repeat Blocks\
A repeat block is a text fragment, a list, or a table row - defined by a Word bookmark - that contains merge fields and that will be repeated for each row returned from the database. The main document is any part of the template that is not within a repeat block. You can assign one data source to each repeat block, and multiple data sources to the main document. Only one row of data can be imported to each set on main document merge fields.

Merge Field Names
Anchor
names
names

...

  • Data source and column names must not include Unicode characters.
  • * Data source and column names must begin with a letter (A-Z, a-z).
  • *

    Data source and column names may include the following characters only:
    ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890_

    Note

    If you assigned a different data source separator, you can also use a "." in your data source and column names.

  • Spaces are not allowed anywhere in a merge field.
Info

Use brackets if your column name does not conform to these rules
The exception of these rules is when a column name is enclosed in brackets (for example, «Products.[Product Category]» . To include spaces or unicode characters in the data source column name, use this format:«DataSource.[Column Name]»
For example: «Employees.[Street Address]» . The [Column Name] format allows you to match any SQL column name exactly. Legal characters within the brackets include every character except parentheses () or brackets [].
When creating these fields with WordApplication or editing the field codes manually, the merge field name must be enclosed in quotes. For example, it should be { MERGEFIELD "[data source].[column name]" }. Any modifiers must also go in the quotes, but the formatting options must go after the quotes.

...

  • «$Employee» means the first column in the data source "Employee."
  • * «Employee» means the "Employee" column in the first data source defined in the WordWriter code.

...

An WordWriter merge field can include modifiers. Modifiers are included in parenthesis at the end of the merge field. For example:

Code Block

<<Products.ProductID(Lowercase)>>

If a merge field includes more than one modifier, the modifiers should be separated by commas. Do not include spaces between modifiers. For example:

Code Block

<<Products.ProductID(Fieldname,Lowercase,Optional)>>

...

Fieldname

Use the Fieldname modifier to insert database column headings in a document. For example, in place of the merge field \
«RecordSet.#2(fieldname)», WordWriter will insert the name of the second column in the RecordSet.

Uppercase

If a merge field includes the Uppercase modifier, all text values imported to the merge field will be displayed in uppercase. If a merge field includes both the Uppercase and Lowercase modifiers, the last will be applied.

Lowercase

If a merge field includes the Lowercase modifier, all text values imported to the merge field will be displayed in lowercase. If a merge field includes both the Uppercase and Lowercase modifiers, the last will be applied.

Optional

By default, if a merge field's data source name or column name is not bound to a data source in code, an error will occur. If a merge field contains the Optional modifier, and the merge field is not bound by name to a data source, WordWriter will discard the merge field in the generated document and will not throw an error. \
This modifier makes both a merge field's data source and column optional. For example, for this merge field: \
«Orders.OrderID(Optional)» \
If either the data source "Orders," or the column "OrderId" does not exist, the merge field will be removed without error.\

Note

If a merge field contains a data source number and/or field number (for example «#7.#3») and is not bound to a data source in script, the merge field will be removed without error whether the "Optional" modifier is present or not.

Image

If the image modifier is present and the column of data for the merge field is either of type byte array (byte[]) or SQL BLOB, then the image will be rendered. The image modifier can take optional parameters to format the size of the image (e.g. <<Product.Image(image(1,600,600))>>. For more see Inserting an Image.

Document(format)

The document modifier can be used to insert certain types of documents into docx files where format is either rtf or , html, or docx. This will insert the formatted document into the docx output. For more see Inserting an Embedded Document.

...