Field Codes
- 3 minutes to read
Document fields are used as placeholders for data that might change in a document and for mail merge operations. For more information on fields, see the Fields document.
You can insert fields automatically when you use particular commands, such as InsertPageCountFieldCommand, InsertPageCountFieldCommand or the InsertTableOfContentsCommand commands. You can also manually insert fields to automate different aspects of your document, using the InsertFieldCommand command (CTRL+F9) or programmatically.
To show field codes, use the ShowAllFieldCodesCommand command. To update, right-click in a field, and then select Update Field or select a portion of a document that contains fields and press F9 to execute the UpdateFieldCommand command.
There are three types of fields - MailMerge, Non-MailMerge and Mixed. MailMerge fields are intended for use in a mail merge process. They get their value only if there is a merge data source bound to the RichEditControl. Otherwise, MailMerge fields are displayed as field placeholders, showing its name or a name of a corresponding data column, encompassed in angular brackets as follows:
<<CompanyName>> for the MERGEFIELD coded as { MERGEFIELD CompanyName }
To display field results for MailMerge fields, set the RichEditMailMergeOptions.ViewMergedData to true or execute the ToggleViewMergedDataCommand command.
A significant difference between MailMerge and Non-MailMerge fields is in their behavior when the Document.MailMerge method is executed. The resulting document does not contain fields of a MailMerge type. They are substituted with their values.
Results for Non-MailMerge fields are displayed when the field is updated.
There is also a Mixed field type. It denotes fields that appear as fields of both MailMerge and Non-MailMerge types. The CREATEDATE and INCLUDEPICTURE are examples of such fields.
#Syntax
Field codes appear between curly brackets ( { } ). You can switch between displaying field code and result for a selected field by selecting Toggle Field Codes in the context menu.
When you view a field code in your document, the syntax looks like this:
{ FIELDNAME Properties Optional_Switches }
- FIELDNAME - This is the name of the field.
- Properties - These are any instructions or variables that are used in a particular field. Not all fields have parameters, and in some fields, parameters are optional.
- Optional switches - These are any optional settings that are available for a particular field. Not all fields have switches available, other than those that control the formatting of the field results.
For example, {MERGEFIELD Weather.condition *Upper} field denotes the MERGEFIELD field bound to the Weather.condition data field displaying the text in all caps.
#Supported Fields
| Field Name | Functionality |
|---|---|
| CREATEDATE | Inserts current date and time. After mail merge the field is replaced with the date and time of the mail merge operation. |
| DATE | Inserts current date and time. |
| TIME | Inserts current time. |
| DOCVARIABLE | Enables you to programmatically insert complex content when this field is updated. |
| HYPERLINK | Enables you to navigate to another location or to a bookmark. |
| IF | Compares two values and inserts the text according to the result of comparison. |
| INCLUDEPICTURE | Inserts the specified image. |
| MERGEFIELD | Retrieves value from the bound data source. |
| NUMPAGES | Inserts the total number of pages. |
| PAGE | Inserts the number of the page containing the field. |
| SEQ | Provides sequential numbering in the document. |
| TC | Defines entries for the table of contents. |
| TOC | Builds a table of contents. |
#Formatting Options
The following formatting switches are supported.