Skip to main content

FieldCollection Class

A collection of the Field objects.

Declaration

export class FieldCollection extends Collection<Field>

Inherited Members

Inheritance

Collection<T>
FieldCollection

Methods

create(position) Method

Creates a new field.

Declaration

create(
    position: number | Interval,
    code?: string
): Field

Parameters

Name Type Description
position number | Interval

A position in the document or a document interval.

code string

A field code.

Returns

Type Description
Field

The newly created field object.

Remarks

You can use the create method to create a new field:

  • Specify a document position to insert a field and a field code.

    // creates the {time} field
    richEdit.selection.activeSubDocument.fields.create(richEdit.selection.active, 'time').update();
    
  • Specify a document interval to be wrapped in a new field.

    You can use this approach to wrap a field in another field. The code sample below demonstrates how to display a DOCVARIABLE field result in upper case.

    richEdit.events.calculateDocumentVariable.addHandler(function(s, e) {
      switch(e.variableName) {
        case 'SomeName': e.value = 'result'; break;
        case 'UpperCase': e.value = e.args[0].toUpperCase(); break;
      }
    });
    var fields = richEdit.selection.activeSubDocument.fields;
    // creates a new field: {DOCVARIABLE SomeName}
    var innerField = fields.create(richEdit.selection.active, 'DOCVARIABLE SomeName');
    // wraps the field with another field: {{DOCVARIABLE SomeName}}
    var outerField = fields.create(innerField.interval);
    // adds a field code to the outer field and transforms the innerField to a field argument
    // {DOCVARIABLE UpperCase "{DOCVARIABLE SomeName}"}
    richEdit.selection.activeSubDocument.insertText(outerField.codeInterval.start, 'DOCVARIABLE UpperCase "');
    richEdit.selection.activeSubDocument.insertText(outerField.codeInterval.end, '"');
    // {DOCVARIABLE UpperCase "{DOCVARIABLE SomeName}result>"}RESULT>
    outerField.update();
    

The newly created field has no result value until the field is updated. To update the field, use the UI or call the update or updateAllFields method.

See Also

createMergeField(position, name) Method

Creates a new merge field.

Declaration

createMergeField(
    position: number,
    name: string
): Field

Parameters

Name Type Description
position number

A position in the document.

name string

The name of a data source column.

Returns

Type Description
Field

The newly created field.

Remarks

The newly created field has no result value until the field is updated. To update the field, use the UI or call the update or updateAllFields method.

var subDocument = richEdit.selection.activeSubDocument;
var field = subDocument.fields.createMergeField(richEdit.selection.active, 'City');
field.update(function(self) {
    console.log(subDocument.getText(self.resultInterval)); // returns "<<City>>" 
});

Run Demo: Mail Merge

find(position) Method

Returns a list of fields that traverse the specified position or interval.

Declaration

find(
    position: number | IInterval
): Field[]

Parameters

Name Type Description
position number | IInterval

A document position or interval.

Returns

Type Description
Field[]

A list of fields.

Remarks

var subDocument = richEdit.selection.activeSubDocument;
var fields = subDocument.fields.find(richEdit.selection.active);
fields.forEach(function(field) {
    console.log(subDocument.getText(field.interval));
});

showAllFieldCodes Method

Displays field codes in place of the fields in the document.

Declaration

showAllFieldCodes(
    doInAllSubDocuments?: boolean
): void

Parameters

Name Type Description
doInAllSubDocuments boolean

true, to display field codes in all sub-documents, false, to display field codes in the current sub-document only.

showAllFieldResults Method

Displays field results in place of the fields in the document.

Declaration

showAllFieldResults(
    doInAllSubDocuments?: boolean
): void

Parameters

Name Type Description
doInAllSubDocuments boolean

true, to display field results in all sub-documents, false, to display field results in the current sub-document only.

updateAllFields Method

Updates and displays all field results.

Declaration

updateAllFields(
    callback?: () => void,
    options?: UpdateFieldsOptions
): boolean

Parameters

Name Type Description
callback () => void

A function that is called after fields are updated.

options UpdateFieldsOptions

An object that contains update options.

Returns

Type Description
boolean

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

Remarks

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