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

  This is the name of the field (the field code). See the Field Codes topic for the supported field codes and their structure.

• 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

  Not currently supported. (These are any optional settings that are available for a specific field. Not all fields have switches available, other than those that control the formatting of the field results.)

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)

  A position in a sub-document text buffer where a field starts.

• Length (Field.length)

  The number of characters in a field within the text buffer.

• Display mode (Field.showCode)

  The current display mode of a field (code or result).

• Hyperlink type related settings (Field.hyperlinkAnchor, Field.hyperlinkTip, Field.hyperlinkUri)

  Settings that define a hyperlink for a field of the HYPERLINK type.

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.