FieldCollection Class

A collection of the Field objects.

Declaration

export class FieldCollection extends Collection<Field>

Inherited Members

count

getByIndex(index)

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.

  JS

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

  JS

  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.

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.

JS

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

JS

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

JS

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