Field Class

A field in a sub-document.

Namespace : DevExpress.Blazor.RichEdit

Assembly : DevExpress.Blazor.RichEdit.v25.2.dll

NuGet Package : DevExpress.Blazor.RichEdit

Declaration

csharp

public class Field :
    DocumentElementBase,
    IIndexBasedTransactionalObject,
    ITransactableObject

Remarks

A field is a placeholder for data that can change, for instance, a page number, or the current date and time. The Rich Text Editor replaces fields with actual data when it updates fields or prints a document.

Use the Fields property to access methods that allow you to create, get, update fields, and change their display mode.

razor

<DxRichEdit @ref="@richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Field dateField = await documentAPI.Fields.CreateAsync(0, "DATE");
            await documentAPI.Fields.UpdateAsync(dateField);
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Field Structure

The Rich Text Editor stores fields in the following form: {Code}Result>. For instance, the field that calculates the current date is stored as {DATE}4/30/2021>.

The Code part specifies how the Result part should be calculated when the field is updated. In a document, a field can be displayed as a code or result according to the field’s display mode.

A field’s Code part 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.

Create Fields

You can create a field in the following ways:

Pass a position and a Code to the CreateAsync(Int32, String, CancellationToken) method to insert a field in the specified position.
Call the CreateAsync(Interval, CancellationToken) or CreateAsync(Int32, Int32) method to wrap an interval that contains a Code in a new field.

The Rich Text Editor allows users to create commonly used fields with ribbon commands and hotkeys. Refer to the following section for additional information on supported fields: Supported Fields.

Access Fields

Call the GetAsync(Int32, CancellationToken) method to access a field by its index in a sub-document. To get all fields a sub-document contains, call the GetAllAsync(CancellationToken) method.

The following example accesses the first field and all fields in the main sub-document:

razor

<DxRichEdit @ref="@richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Field firstField = await documentAPI.Fields.GetAsync(0);
            IReadOnlyList<Field> allFields = await documentAPI.Fields.GetAllAsync();
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

You can get text intervals that contain a field code (CodeInterval), field result (ResultInterval), or entire field (Interval). To get a Text Span in the specified interval, call the GetTextSpanAsync(Interval, CancellationToken) method.

razor

<DxRichEdit @ref="@richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Field field = await documentAPI.Fields.CreateAsync(0, "DATE"); // Creates the DATE field
            await documentAPI.GetTextSpanAsync(field.Interval); // Returns a Text Span that contains "{DATE}>"
            await documentAPI.Fields.UpdateAsync(field); // Calculates the field result
            field = await documentAPI.Fields.GetAsync(field.Index); // Gets the updated field
            await documentAPI.GetTextSpanAsync(field.Interval); // Returns a Text Span that contains "{DATE}4/30/2021>"
            await documentAPI.GetTextSpanAsync(field.CodeInterval); // Returns a Text Span that contains "DATE"
            await documentAPI.GetTextSpanAsync(field.ResultInterval); // Returns a Text Span that contains "4/30/2021"
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Update Fields

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

Call the UpdateAllAsync(Boolean, CancellationToken) method to update every field in a sub-document or in all sub-documents.
Call the UpdateAsync(Field, CancellationToken) method to update a field.
Select the Mail Merge → Update All Fields ribbon command to update all fields in a document.
Select the References → Update Table ribbon command to update a TOC field.
Select a range that contains field(s) and press F9 to update the field(s).

Delete Fields

A field’s Interval property allows you to get the interval that contains the field. Pass a field’s interval to the sub-document’s RemoveAsync(Interval, CancellationToken) method to delete the field.

The following example deletes the first field in the main sub-document:

razor

<DxRichEdit @ref="@richEdit" />

@code {
    DxRichEdit richEdit;
    Document documentAPI;
    @* ... *@
    /* Surround the code that contains an asynchronous operation with a try-catch block to handle
    the OperationCanceledException. This exception is thrown when an asynchronous operation is canceled. */
        try {
            documentAPI = richEdit.DocumentAPI;
            @* ... *@
            Field fieldToDelete = await documentAPI.Fields.GetAsync(0);
            await documentAPI.RemoveAsync(fieldToDelete.Interval);
            @* ... *@
        }
        catch (OperationCanceledException e) {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
}

Display Mode

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

Call the ShowAllFieldCodesAsync(Boolean, CancellationToken) or ShowAllFieldResultsAsync(Boolean, CancellationToken) method to specify the display mode of every field in a sub-document or in all sub-documents.
Call the ToggleViewAsync(Field, CancellationToken) method to change the display mode of a field.
Select the Mail Merge → Show All Field Codes or Show All Field Results ribbon command to set display mode of a document’s fields.
Press Alt+F9 to change display mode of a document’s fields.

Supported 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 create this field in the following ways:

Call a CreateAsync method overload.
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"... }

You can create this field in the following ways:

Call a CreateAsync method overload.
Select Mail Merge → Create Field → DOCVARIABLE ribbon command.

When a DOCVARIABLE field is updated, the Rich Text Editor fires the CalculateDocumentVariable event. Specify the event handler to calculate the field result.

async Task OnCalculateDocumentVariable(CalculateDocumentVariableEventArgs eventArgs) {
    try {
        switch(eventArgs.VariableName) {
            case "paragraphCount":
                var paragraphs = await richEdit.DocumentAPI.Paragraphs.GetAllAsync();
                eventArgs.Value = paragraphs.Count.ToString();
                break;
            default:
                break;
        }
    } catch(OperationCanceledException e) {
        Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
    }
}

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 Rich Text Editor does not update the FILLIN field when the document is printed.

You can create this field in the following ways:

Call a CreateAsync method overload.
Select the Mail Merge → Create Field 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 email address.

{ HYPERLINK "location" }

Use the sub-document’s Hyperlinks and the Bookmarks properties to access hyperlinks and bookmarks.

You can create this field in the following ways:

Call a CreateAsync method overload.
Call a CreateAsync method to add a hyperlink to a sub-document.
The Rich Text Editor automatically transforms web references, email addresses, or network paths to hyperlinks as you type.
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 CreateAsync method overloads:
Select the following ribbon command: Mail Merge → Create Field → IF.

MERGEFIELD

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

{ MERGEFIELD "field name" }

You can create this field in the following ways:

Call a CreateAsync method overload.
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 create this field in the following ways:

Call a CreateAsync method overload.
Select the Mail Merge → Create Field → NUMPAGES ribbon command.
Select the Insert → Page Count ribbon command.

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 bookmarks. A bookmark’s Name property returns the name of the bookmark.

Switch	Description
\h	Creates a hyperlink to the bookmark.

You can create this field in the following ways:

Call a CreateAsync method overload.
Select the Mail Merge → Create Field ribbon command or press Ctrl+F9 to insert an empty field and type in the PAGEREF code.

SEQ

Sequential 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 create this field in the following ways:

Call a CreateAsync method overload.
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 create this field in the following ways:

Call a CreateAsync method overload.
Select the Mail Merge → Create Field 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 create this field in the following ways:

Call a CreateAsync method overload.
Select the Mail Merge → Create Field → TIME ribbon command.
Press Alt+Shift+T.

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 sequence numbers and page numbers. The default separator is a tab with leader dots. You can use up to five characters enclosed in quotation marks.

You can create this field in the following ways:

Call a CreateAsync method overload.
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.

Inheritance

Object DevExpress.Blazor.RichEdit.Internal.DocumentObject DocumentElementBase Field