Fields

Sep 09, 2024
4 minutes to read

A field is a special placeholder for non-static data that can change, for instance, a page number or date and time.

A field is implemented as the Field client object. Use the SubDocument.fields property to access a collection of a sub-document’s fields. The RichEditDocumentBase.fields property returns a collection of the main sub-document‘s fields.

javascript

richEdit.selection.activeSubDocument.fields; // gets the active sub-document's fields
richEdit.document.fields; // gets the main sub-document's fields

Refer to the following section for examples: Field Examples.

Field Structure

A field has the {Code}Result> structure in the text buffer, for instance, {DATE}11/2/2020>.

The Code specifies how the Result should be calculated when the field is updated. In a document, a field can be displayed as a field code or field result.

You can get text buffer intervals that contain a field code (codeInterval), a field result (resultInterval), and an entire field (interval). To get the sub-document’s text buffer, call the getText method.

javascript

var field = richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'DATE');
richEdit.document.getText(field.interval); // returns "{DATE}>"
field.update(); // calculates the field result
richEdit.document.getText(field.interval); // returns "{DATE}11/2/2020>"
richEdit.document.getText(field.codeInterval); // returns "DATE"
richEdit.document.getText(field.resultInterval); // returns "11/2/2020"

The Code part of a field has the following syntax.

FIELDNAME Properties Optional_Switches

FIELDNAME - the name of the field.
Properties - any instructions or variables that are used in a particular field.
Optional switches - parameters that contain additional information.

Refer to the following section for a list of supported field codes and their structures: Supported Fields.

Insert a Field

You can insert a field into a document in the following ways (the examples below demonstrate how to insert the DATE field):

Call the create(position) method.
Call the executeCommand(commandId) method.
Select a ribbon command, for instance, Mail Merge → Create Field → DATE.
Use a shortcut, for instance, ALT + SHIFT + D.
Press CTRL + F9 to insert an empty field and add the field code.

Refer to the following section for instructions on how to insert a particular field into a document: Supported Fields.

Update a Field

Update a field to calculate and display the field result. You can use API members or the UI to update a field.

Update all fields in a document

Call the executeCommand(commandId) method with the UpdateAllFields command as a parameter.
Call the updateAllFields method.
Select the Mail Merge → Update All Fields ribbon command.

Update all fields in a sub-document

Call the updateAllFields method and set its doInAllSubDocuments parameter to false.

Update all fields in the selection

Select a range that contains fields and do one of the following:

Call the executeCommand(commandId) method with the UpdateField command as a parameter.
Right click the selection, and select the Update Field context menu command.
Press F9.

Update a particular field

Call a field’s update method.
Right click a field and select the Update Field context menu command.
Select a field and press F9.

Update a TOC field

Call the executeCommand(commandId) method with the UpdateTableOfContents command as a parameter.
Select the References → Update Table ribbon command.

Display Mode

The Rich Text Editor can display a field as a code (for instance, { DATE } ) or result (for instance, 11/2/2020 ). You can use API members or the UI to switch between modes.

Set display mode of all fields in a document

Call the executeCommand(commandId) method with the ShowAllFieldCodes or ShowAllFieldResults command as a parameter.
Call the showAllFieldCodes or showAllFieldResults method.
Select the Mail Merge → Show All Field Codes or Show All Field Results ribbon command.
Press ALT + F9.

Set display mode of all fields in a sub-document

Call the showAllFieldCodes or showAllFieldResults method and set its doInAllSubDocuments parameter to false.

Set display mode of a field

Set a field’s isShowCode property.
Right click a field and select the Toggle Field Codes context menu command.