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.

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

• 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
• Client 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);
        })
    }")
...
)

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.

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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.

You can insert the field in the following ways:

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

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

• 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] }

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.

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

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

You can insert the field in the following ways:

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

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

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