Field Class

Defines a field in the document.

Declaration

export class Field

Remarks

Fields are special placeholders for non-static data that might change (for instance, page numbers, actual dates and times).

A field is specified by a field code, and can be viewed within a document as either a field code or a field result. The field code specifies how the field result should be calculated when the field is updated.

A field has the following structure in the text buffer: {Code}Result>; for instance, {DATE}09-Oct-18>.

Refer to the following section for a list of supported fields: Supported Fields

JS

var subDocument = richEdit.selection.activeSubDocument;
var field = subDocument.fields.create(richEdit.selection.active, 'time');
field.update(function(self) {
    console.log('Result: ' + subDocument.getText(self.resultInterval));
});

Inheritance

Field

Hyperlink

Properties

codeInterval Property

Gets the text buffer interval that contains the field’s code.

Declaration

readonly codeInterval: Interval

Property Value

Type	Description
Interval	The text buffer interval.

Remarks

A field has the following structure in the text buffer: {Code}Result>; for instance, {DATE @ “M/d/yyyy”}6/20/2019>.

Use the codeInterval property to get the text buffer interval that contains the field’s code.

JS

var field = richEdit.document.fields.getByIndex(0);

// returns "{DATE \@ "M/d/yyyy"}6/20/2019>"
field.document.getText(field.interval);

// returns "DATE \@ "M/d/yyyy""
richEdit.document.getText(field.codeInterval);

// returns "6/20/2019"
richEdit.document.getText(field.resultInterval);

index Property

Gets the field’s index in a field collection.

Declaration

readonly index: number

Property Value

Type	Description
number	A zero-based index.

Remarks

You can use the getByIndex(index) method to find a field by its index in the FieldCollection object.

JS

var subDocument = richEdit.selection.activeSubDocument;
var field = subDocument.fields.create(richEdit.selection.active, 'time');
var nextField = subDocument.fields.getByIndex(field.index + 1);

interval Property

Gets the text buffer interval that contains the field.

Declaration

readonly interval: Interval

Property Value

Type	Description
Interval	The text buffer interval.

Remarks

A field has the following structure in the text buffer: {Code}Result>; for instance, {DATE @ “M/d/yyyy”}6/20/2019>.

Use the interval property to get the text buffer interval that contains the entire field.

JS

var field = richEdit.document.fields.getByIndex(0);

// returns "{DATE \@ "M/d/yyyy"}6/20/2019>"
field.document.getText(field.interval);

// returns "DATE \@ "M/d/yyyy""
richEdit.document.getText(field.codeInterval);

// returns "6/20/2019"
richEdit.document.getText(field.resultInterval);

isHyperlink Property

Returns whether the field is a hyperlink.

Declaration

readonly isHyperlink: boolean

Property Value

Type	Description
boolean	true, if the field is a hyperlink; otherwise; false.

isShowCode Property

Specifies whether the field’s code or result is visible.

Declaration

isShowCode: boolean

Property Value

Type	Description
boolean	true, if the field code is visible; false, if the field result is visible.

Remarks

JS

var field = richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'time');
field.isShowCode = false;

name Property

Returns the name of the field.

Declaration

readonly name: FieldName

Property Value

Type	Description
FieldName	The field name.

Remarks

JS

var field = richEdit.document.fields.create(0, 'time \\@ "dd/MM HH:mm"');
// checks if the RichEdit identified the time field
field.name == DevExpress.RichEdit.FieldName.Time; // returns true

resultInterval Property

Gets the text buffer interval that contains the field’s result.

Declaration

readonly resultInterval: Interval

Property Value

Type	Description
Interval	The text buffer interval.

Remarks

A field has the following structure in the text buffer: {Code}Result>; for instance, {DATE @ “M/d/yyyy”}6/20/2019>.

Use the resultInterval property to get the text buffer interval that contains the field’s result.

JS

var field = richEdit.document.fields.getByIndex(0);

// returns "{DATE \@ "M/d/yyyy"}6/20/2019>"
field.document.getText(field.interval);

// returns "DATE \@ "M/d/yyyy""
richEdit.document.getText(field.codeInterval);

// returns "6/20/2019"
richEdit.document.getText(field.resultInterval);

subDocument Property

Gets the sub-document where the field is placed.

Declaration

readonly subDocument: SubDocument

Property Value

Type	Description
SubDocument	The sub-document that contains the field.

Methods

delete Method

Deletes the current field.

Declaration

delete(): void

Remarks

JS

richEdit.document.fields.getByIndex(0).delete();

update Method

Updates and displays the field’s result.

Declaration

update(
    callback?: (self: Field) => void
): boolean

Parameters

Name	Type	Description
callback	(self: Field) => void	A function that is called after the field is updated.

Returns

Type	Description
boolean	true, if the field has been updated successfully; otherwise, false.

Remarks

JS

var subDocument = richEdit.selection.activeSubDocument;
var field = subDocument.fields.create(richEdit.selection.active, 'time');
field.update(function(self) {
    console.log('Result: ' + subDocument.getText(self.resultInterval));
});

JS

rich.beginUpdate();
rich.history.beginTransaction();
for(var i = 0, field; field = rich.document.fields.getByIndex(i); i++)
    if (field.name == DevExpress.RichEdit.FieldName.FillIn)
        field.update();
rich.history.endTransaction();
rich.endUpdate();

JS

richEdit.history.beginTransaction();
richEdit.beginUpdate();
richEdit.document.fields.updateAllFields(function () {  
    richEdit.document.subDocuments.forEach(function (subDocument) {
        for (var i = 0, field; field = subDocument.fields.getByIndex(i); i++)
            richEdit.document.setCharacterProperties(field.resultInterval, { bold: true });
    });
    richEdit.endUpdate();
    richEdit.history.endTransaction();  
}, new DevExpress.RichEdit.UpdateFieldsOptions(true, false));  

To update all field results, use the updateAllFields method.

JS

var doInAllSubDocuments = true;
var updateTocFields = true;
var options = new DevExpress.RichEdit.UpdateFieldsOptions(doInAllSubDocuments, updateTocFields);
richEdit.document.fields.updateAllFields(function() {
    console.log('Updated');
}, options);