A newer version of this page is available. Switch to the current version.

Document Fields

  • 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.

FieldScheme

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.
See Also