Fields

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

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.

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.

    richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'DATE');
    
  • Call the executeCommand(commandId) method.

    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.

    richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.UpdateAllFields);
    
  • Call the updateAllFields method.

    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.

    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.

    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.

    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.

    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.

    richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.ShowAllFieldCodes);
    richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.ShowAllFieldResults);
    
  • Call the showAllFieldCodes or showAllFieldResults method.

    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.

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

Set display mode of a field

  • Set a field's isShowCode property.

    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.