Fields

• Aug 08, 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.

Run Demo

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.

JS

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.

JS

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.

  JS

  richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'DATE');
  

• Call the executeCommand(commandId) method.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.CreateDateField);
  

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

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.UpdateAllFields);
  

• Call the updateAllFields method.

  JS

  richEdit.selection.activeSubDocument.fields.updateAllFields();
  

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

  JS

  richEdit.selection.activeSubDocument.fields.updateAllFields(undefined, {doInAllSubDocuments: 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.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.ContextMenuCommandId.UpdateField);
  

• Right click the selection, and select the Update Field context menu command.
• Press F9.

Update a particular field

• Call a field’s update method.

  JS

  richEdit.selection.activeSubDocument.fields.getByIndex(0).update();
  

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

  JS

  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.UpdateTableOfContents);
  

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

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.ShowAllFieldCodes);
  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.ShowAllFieldResults);
  

• Call the showAllFieldCodes or showAllFieldResults method.

  JS

  richEdit.selection.activeSubDocument.fields.showAllFieldCodes();
  richEdit.selection.activeSubDocument.fields.showAllFieldResults();
  

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

  JS

  richEdit.selection.activeSubDocument.fields.showAllFieldCodes(false);
  richEdit.selection.activeSubDocument.fields.showAllFieldResults(false);
  

Set display mode of a field

• Set a field’s isShowCode property.

  JS

  var field = richEdit.selection.activeSubDocument.fields.getByIndex(0);
  field.isShowCode = !field.isShowCode;
  

• Right click a field and select the Toggle Field Codes context menu command.