Supported Fields

• Dec 03, 2024
• 9 minutes to read

This topic describes field codes you can use in the Rich Text Editor.

Refer to the following section for more information about fields: Fields.

DATE

Inserts the current date.

{ DATE [ \@ "switch" ] }

The switch specifies the date-time format applied to the field result. The default format is “M/d/yyyy”.

You can insert the field in the following ways:

• Call the create(position) method with the ‘DATE’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateDateField command as a parameter.

  JS

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

• Select the Mail Merge → Create Field → DATE ribbon command.

• Press ALT+SHIFT+D.

DOCVARIABLE

Inserts a value assigned to the document variable.

{ DOCVARIABLE "variable name" "argument1" "argument2"... }

When a DOCVARIABLE field is updated, the Rich Text Editor fires one of the following events that allow you to calculate the field result:

• The CalculateDocumentVariable event fires for every updated DOCVARIABLE field.
• The CalculateDocumentVariableAsync event fires once for all updated DOCVARIABLE fields.

Note

When the CalculateDocumentVariableAsync event handler is specified, the CalculateDocumentVariable event does not fire.

You can specify an event handler on the server or on the client.

.NET Core Server Settings

@(Html.DevExpress().RichEdit("richEdit")
    .OnCalculateDocumentVariable("function(s,e){
        if (e.variableName == 'sectionIndex')
            e.value = (s.document.sections.find(e.fieldInterval.start).index + 1).toString();
    }")
    // or
    .OnCalculateDocumentVariableAsync("function(s,e){
        e.data.forEach(function(data) {
            data.callback('ResultOf' + data.variableName);
        })
    }")
...
)

Client Settings

const options = DevExpress.RichEdit.createOptions();
options.events.calculateDocumentVariable = ("function(s,e){
        if (e.variableName == 'sectionIndex')
            e.value = (s.document.sections.find(e.fieldInterval.start).index + 1).toString();
    }");
// or
options.events.calculateDocumentVariableAsync = ("function(s,e){
        e.data.forEach(function(data) {
            data.callback('ResultOf' + data.variableName);
        })
    }");

You can insert the field in the following ways:

• Call the create(position) method with the ‘DOCVARIABLE’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateEmptyDocVariableField command as a parameter.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabItemId.CreateEmptyDocVariableField);
  

• Select Mail Merge → Create Field → DOCVARIABLE ribbon command.

FILLIN

Displays a dialog box and inserts a user’s response as a field result.

{ FILLIN ["prompt"] [\d "default response"]}

The dialog box appears every time you update the field. The RichEdit control does not update the FILLIN field when the document is printed.

You can insert the field in the following ways:

• Call the create(position) method with the ‘FILLIN’ parameter.

  JS

  var subDocument = richEdit.selection.activeSubDocument;
  subDocument.fields.create(richEdit.selection.active, 'FILLIN "Type your name" \d "John Doe" ');
  

  

• Select the Mail Merge → Create Field → Empty ribbon command or press CTRL+F9 to insert an empty field and type the FILLIN code.

HYPERLINK

Inserts a hyperlink into a bookmark, URL, or e-mail address.

{ HYPERLINK "location" }

Use the sub-document’s hyperlinks and the bookmarks properties to access collections of hyperlinks and bookmarks. Handle the hyperlinkClick event to perform custom actions when a user clicks a hyperlink.

You can insert the field in the following ways:

• Call the hyperlinks.create(position,hyperlinkInfo) method.

  JS

  var linkInfo = new DevExpress.RichEdit.HyperlinkInfo("Visit our site", "https://www.devexpress.com/", "", "DevExpress site")
  richEdit.document.hyperlinks.create(richEdit.selection.active, linkInfo);
  

• Call the bookmarks.create(interval,name) method.

  JS

  var textInterval = richEdit.document.insertText(0, 'text');
  var bookmark = richEdit.document.bookmarks.create(textInterval, 'bookmarkName');
  

• Call the fields.create(position) method with the ‘HYPERLINK’ parameter.

  JS

  var subDocument = richEdit.selection.activeSubDocument;
  subDocument.fields.create(richEdit.selection.active, 'HYPERLINK "www.google.com"');
  

• Call the executeCommand(commandId) method with the ShowHyperlinkDialog command as a parameter. Then, specify a hyperlink’s settings in the Hyperlink dialog.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.InsertTabCommandId.ShowHyperlinkDialog);
  

• The RichEdit control automatically (as you type) transforms web references, email addresses or network paths to hyperlinks. Use the DetectUrls property to disable this functionality.

  .NET Core Server Settings

  @(Html.DevExpress().RichEdit("DemoRichEdit")
      .AutoCorrect(a => a
          .DetectUrls(false)
  ...
  

  Client Settings

  const options = DevExpress.RichEdit.createOptions();
  options.autoCorrect.detectUrls = false;
  

• Select the Insert → Hyperlink ribbon command.

IF

Compares two values and inserts a text string related to the comparison result. The IF field has the following valid syntaxes:

{ IF expression trueText falseText }

Displays trueText if the expression is not an empty string. Otherwise, displays falseText.

{ IF leftExpression operator rightExpression trueText falseText}

Displays trueText if the leftExpression operator rightExpression condition is true. Otherwise, displays falseText.

You can omit either trueText or falseText in both cases.

Expressions can be either strings of characters, numbers, or nested fields that return values. rightExpression supports wildcard characters. For example, ? matches a single character, and * matches any number of characters.

Note

Separate all parts of the IF function by spaces.
Enclose expressions and resulting text strings in quotation marks if they contain space characters.

The IF function supports the following comparison operators:

• = (equals)
• <> (not equal)
• > (greater than)
• >= (greater than or equal)
• < (less than)
• <= (less than or equal)

You can create an IF field as follows:

• Call the create(position) method with the ‘IF’ parameter.

  JS

  var subDocument = richEdit.selection.activeSubDocument;
  subDocument.fields.create(richEdit.selection.active, 'IF 5 < 10 \"less than 10\" \"not less than 10\"');
  

• Call the executeCommand(commandId) method with the CreateEmptyIfField command as a parameter.

  JS

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

MERGEFIELD

Inserts information from the specified data field of the bound data source. Refer to the Mail Merge topic for more information.

{ MERGEFIELD "field name" }

You can insert the field in the following ways:

• Call the create(position) method with the ‘MERGEFIELD’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateEmptyMergeField command as a parameter.

  JS

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

• Call the executeCommand(commandId) method with the ShowInsertMergeFieldDialog command as a parameter and select a field name in the Insert Merge Field dialog.

  JS

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

• Select the Mail Merge → Create Field → MERGEFIELD ribbon command.

• Select the Mail Merge → Insert Merge Field ribbon command.

NUMPAGES

Inserts the total number of pages in the document.

{ NUMPAGES }

You can insert the field in the following ways:

• Call the create(position) method with the ‘NUMPAGES’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateNumPagesField or the InsertPageCountField command as a parameter.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.CreateNumPagesField);
  // or richEdit.executeCommand(DevExpress.RichEdit.InsertTabCommandId.InsertPageCountField);
  

• Select the Mail Merge → Create Field → NUMPAGES ribbon command.

• Select the Insert → Page Count ribbon command.

PAGE

Inserts the number of the current page.

{ PAGE }

You can insert the field in the following ways:

• Call the create(position) method with the ‘PAGE’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreatePageField or the InsertPageNumberField command as a parameter.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.MailMergeTabCommandId.CreatePageField);
  // or richEdit.executeCommand(DevExpress.RichEdit.InsertTabCommandId.InsertPageNumberField);
  

• Select the Mail Merge → Create Field → PAGE ribbon command.

• Select the Insert → Page Number ribbon command.

• Press ALT+SHIFT+P.

PAGEREF

Inserts a number of the page that stores the specified bookmark.

{ PAGEREF bookmark name [ switches ]}

Use the sub-document’s bookmarks property to access a collection of bookmarks. A bookmark’s name property returns the name of the bookmark.

Switch	Description
\h	Creates a hyperlink to the bookmark.

You can insert the field in the following ways:

• Call the create(position) method with the ‘PAGEREF’ parameter.

JS

var bookmarkName = richEdit.selection.activeSubDocument.bookmarks.getByIndex(0).name;
richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'PAGEREF '+ bookmarkName);

• Select the Mail Merge → Create Field → Empty ribbon command or press CTRL+F9 to insert an empty field and type in the PAGEREF code.

SEQ

Sequentially numbers figures, tables, equations, and other items in a document. A table of contents can display SEQ fields.

{ SEQ identifier [ switches ] }

identifier specifies the name of a series of items to number. Predefined identifiers: Figure, Table, and Equation.

Switch	Description
\c	Repeats the closest preceding sequence number.
\h	Hides the field result.
\r number	Resets the sequence number to the specified integer.

You can insert the field in the following ways:

• Call the create(position) method with the ‘SEQ’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateEquationCaptionField, CreateFigureCaptionField, or CreateTableCaptionField command as a parameter.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateEquationCaptionField);
  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateFigureCaptionField);
  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateTableCaptionField);
  

• Select the References → Insert Caption → Equations Caption ribbon command.

• Select the References → Insert Caption → Figures Caption ribbon command.

• Select the References → Insert Caption → Tables Caption ribbon command.

TC

A non-visual field that creates a table of contents entry. This entry can be displayed in a TOC field.

{ TC "text" [ switches ] }

Switch	Description
\f “identifier”	Specifies the field’s group identifier that allows you to display only a particular group’s fields in a table of contents.
\l “level number”	Specifies the level of the TC entry in a table of contents. The default value is 1.

You can insert the field in the following ways:

• Call the create(position) method with the ‘TC’ parameter.

JS

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

• Select the Mail Merge → Create Field → Empty ribbon command or press CTRL+F9 to insert an empty field and type in the TC code.

TIME

Inserts the current time.

{ TIME [ \@ "switch" ] }

The switch specifies the date-time format applied to the field result. The default format is “h:mm am/pm”.

You can insert the field in the following ways:

• Call the create(position) method with the ‘TIME’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the CreateTimeField command as a parameter.

  JS

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

• Select the Mail Merge → Create Field → TIME ribbon command.

• Press ALT+SHIFT+T.

TOC

Generates a table of contents, table of figures, table of tables, or table of equations.

{ TOC [ switches ] }

A table of contents can include heading paragraphs, SEQ fields, and TC fields.

The RichEdit control does not update a TOC field when the document is printed.

Switch	Description
	Without switches the table of contents is built based on heading paragraphs.
\h	Inserts entries as hyperlinks.
\n “levelStart-levelEnd”	Omits page numbers in the table of contents from the specified levels (for instance, { TOC \n 1-1 } omits page numbers from level 1). When the range is not specified, omits page numbers from all levels.
\o “levelStart-levelEnd”	Builds a table of contents from paragraphs with specified outline levels. For example, { TOC \o “1-3” } lists only paragraphs with outline levels 1 through 3.
\c “seq field identifier”	Builds a table of contents from items that have SEQ fields. The SEQ fields’ identifier should match the “seq field identifier”.
\f “TC identifier”	Builds a table of contents from TC fields. TC fields’ identifier should match the “TC identifier”.
\p “separator”	Specifies the characters that separate the sequence numbers and page numbers. The default separator is a tab with leader dots. You can use up to five characters, which must be enclosed in quotation marks.

You can insert the field in the following ways:

• Call the create(position) method with the ‘TOC’ parameter.

  JS

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

• Call the executeCommand(commandId) method with the InsertTableOfContents, CreateTableOfEquationsField, CreateTableOfFiguresField, or CreateTableOfTablesField command as a parameter.

  JS

  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.InsertTableOfContents);
  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateTableOfEquationsField);
  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateTableOfFiguresField);
  richEdit.executeCommand(DevExpress.RichEdit.ReferencesTabCommandId.CreateTableOfTablesField);
  

• Select the References → Table of Contents ribbon command.

• Select the References → Insert Table of Figures → Table of Equations ribbon command.

• Select the References → Insert Table of Figures → Table of Figures ribbon command.

• Select the References → Insert Table of Figures → Table of Tables ribbon command.