Document Fields

Jun 17, 2021
4 minutes to read

Overview

Document fields are special placeholders for non-static data that might change (be updated on field updates). These placeholders are replaced with actual data when the document is rendered for printing or fields are updated directly. Using fields, you can automate different aspects of your document, such as auto page numbering, inserting actual dates and times, etc.

A field is defined by a set of codes that instructs the RichEdit to insert text and graphics into a document automatically. The RichEdit processes field codes and inserts data in the field. The inserted data is called the field result. The process itself is called a field update.

Field Structure

In the text buffer, a field is represented as the following string structure containing five main parts.

{Code}Result>

Open symbol ( { )
Code part
Separator symbol ( } )
Result part
End symbol ( > )

The value of the Result part is created dynamically depending on the Code part type when the field update process is initiated (through the F9 key or the corresponding command in the ribbon or context menu). When the RichEdit opens a document, document fields are not updated.

The Code part has the following syntax.

FIELDNAME Properties Optional_Switches

FIELDNAME
Properties
Optional switches

For example, the {MERGEFIELD Weather.condition *Upper} field denotes the MERGEFIELD field bound to the Weather.condition data field, which displays the text in all caps.

Definition

Programmatically, a field is implemented as the Field client object. A list of field objects in the active sub-document can be accessed through the fieldsInfo client property (SubDocument.fieldsInfo) in the following notation:

clientRichEditName.document.activeSubDocument.fieldsInfo

A document field can be defined using the following characteristics.

Start position (Field.start)
Length (Field.length)
Display mode (Field.showCode)
Hyperlink type related settings (Field.hyperlinkAnchor, Field.hyperlinkTip, Field.hyperlinkUri)

Client API

The following client commands are available for manipulating fields in a document. Call the commands in the notation given below:

clientRichEditName.commands.commandName.execute(parameter_if_any)

Command Name	Link	Description
createDateField	RichEditCommands.createDateField	Gets a command to insert and update a field with a DATE code.
createField	RichEditCommands.createField	Gets a command to add a field at the current position in a document.
createMergeField	RichEditCommands.createMergeField	Gets a command to replace the selection with a MERGEFIELD (a data source column name is passed with a parameter).
createPageCountField	RichEditCommands.createPageCountField	Gets a command to replace the selection with a NUMPAGES field displaying the total number of pages.
createPageField	RichEditCommands.createPageField	Gets a command to replace the selection with a PAGE field displaying the current page number.
createTimeField	RichEditCommands.createTimeField	Gets a command to replace the selection with a TIME field displaying the current time.
mergeFieldDialog	RichEditCommands.mergeFieldDialog	Gets a command to invoke the Insert Merge Field dialog window.
showAllFieldCodes	RichEditCommands.showAllFieldCodes	Gets a command to display all field codes in place of the fields in the document.
showFieldCodes	RichEditCommands.showFieldCodes	Gets a command to display the selected field’s codes.
updateAllFields	RichEditCommands.updateAllFields	Gets a command to update all fields in the document.
updateField	RichEditCommands.updateField	Gets a command to update each field’s result in the selection.