Fields
- 5 minutes to read
This topic consists the following sections:
Overview
The Field is a set of codes that instructs the RichEditDocumentServer to insert text or graphics into a document automatically. The field code syntax is illustrated and described below.
- Field Name - the name of the current field. Refer to the Field Codes section for a list of all available fields.
- Property - instruction/variable used in a particular field. This is an optional element.
- Switch - an additional parameter that offers more information. This is an optional element. Refer to the Format Switches section for a list of supported format switches.
A field in the document consists of two ranges - the Field.CodeRange and the Field.ResultRange. Use the Field.Range property to obtain the total range the field occupies.
The RichEditDocumentServer supports the following field types:
Non-MailMerge
Regular fields used to insert a simple data, such as DATE, TIME or PAGE. The Non-MailMerge field results are shown after the update.
MailMerge
Fields used in the Mail Merge process. They get a value only if there is a mail merge data source bound to the RichEditDocumentServer. In the resulting document, MailMerge fields are evaluated and substituted with the resulting values.
Mixed
Fields which do not require a data source to get its value, such as INCLUDEPICTURE and CREATEDATE. They are substituted with the resulting values during mail merge.
Formula
The = (Formula) field is a code that uses mathematical formulas and numeric field values to calculate a number. The formula field syntax looks as follows:
{={NUMERIC FIELD} Operator {NUMERIC FIELD}}
The RichEditDocumentServer supports the following operators in the formula field:
- Addition (+)
- Subtraction (-)
- Multiplication (*)
- Division (/)
- Powers and Roots (^)
- Equal to (=)
- Less than (<)
- Less than or equal to (<=)
- Greater than (>)
- Greater than or equal to (>=)
- Not equal to (<>)
You can change the field’s numeric format. Refer to the Numeric Format Switch topic for a list of available format switches.
Insert and Modify Fields
Members from the table below allow you to insert and modify the field programmatically.
| Member | Description |
|---|---|
| SubDocument.BeginUpdate | Opens the document for editing. |
| FieldCollection.Create | Creates a new Field object. |
| SubDocument.Fields | Provides access to the collection of fields in the current document. |
| Field.Range | Gets the document range occupied by the field. |
| Field.CodeRange | Gets the range containing the field codes. |
| Field.ResultRange | Gets the range containing the field result. |
| SubDocument.InsertText | Inserts the specified text at the specified position. |
| SubDocument.EndUpdate | Finalizes the modification. |
Note
A complete sample project is available at https://github.com/DevExpress-Examples/word-processing-document-api-examples-t418535
Document document = server.Document;
document.BeginUpdate();
document.Fields.Create(document.CaretPosition, "DATE");
document.EndUpdate();
for (int i = 0; i < document.Fields.Count; i++)
{
string fieldCode = document.GetText(document.Fields[i].CodeRange);
if (fieldCode == "DATE")
{
DocumentPosition position = document.Fields[i].CodeRange.End;
document.InsertText(position, @" \@ ""M / d / yyyy HH: mm:ss""");
}
}
document.Fields.Update();
Note
The header, footer, text box and comment in the word processing document do not belong to the main document body.
The TextBox.Document property allows you to retrieve the text box content and update the corresponding fields.
Use the Section.BeginUpdateHeader - Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to obtain the header or footer. Refer to the Headers and Footers topic for details.
Update Fields
Most fields are updated automatically when the document is saved or printed, or during the mail merge operation. Use the Field.Update method to update the field on demand. Specify the DocumentImporterOptions.UpdateField property to set what document fields should be updated automatically when loading the document. Use the docServer.Options.Import.DocumentFormat.UpdateField notation (where DocumentFormat is one of the RichTextEditDocumentImportOptions properties) to access this property.
Set the field’s Field.Locked property to true to prevent a specific field from being updated. Use the FieldOptions.UpdateLockedFields option to allow updating locked fields.
The DOCVARIABLE field is not updated during mail merge or document insertion. Handle the RichEditDocumentServer.CalculateDocumentVariable event to update the DOCVARIABLE fields’ values.
The RichEditDocumentServer.CalculateDocumentVariable event does not occur for a locked DOCVARIABLE field, and the field value remains unchanged. Set the FieldOptions.UpdateLockedFields option to the UpdateLockedFields.DocVariableOnly value to update DOCVARIABLE fields.
Tip
Refer to the following repositories for code sample projects:
Field Options
Use the Field.ShowCodes property to change the target field’s display mode.
This code snippet displays field codes for all fields in the main document body.
The fields containing in the header or footer belong to a different FieldCollection. Use the Section.BeginUpdateHeader- Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to retrieve the header or footer document.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/word-processing-document-api-examples-t418535
Document document = server.Document;
document.LoadDocument("MailMergeSimple.docx", DocumentFormat.OpenXml);
for (int i = 0; i < document.Fields.Count; i++)
{
document.Fields[i].ShowCodes = true;
}
Use the RichEditControlOptionsBase.Fields to specify how RichEditDocumentServer should process and display document fields, as shown in the code snippet below:
FieldOptions fieldOptions = docServer.Options.Fields;
fieldOptions.HighlightMode = FieldsHighlightMode.Always;
fieldOptions.HighlightColor = System.Drawing.Color.LightSalmon;
fieldOptions.UseCurrentCultureDateTimeFormat = true;
fieldOptions.ThrowExceptionOnInvalidFormatSwitch = true;
fieldOptions.UpdateFieldsInTextBoxes = true;
Set the RichEditMailMergeOptions.ViewMergedData to true to display the MERGEFIELD fields code results.
Set the DocumentCapabilitiesOptions.Fields property to DocumentCapability.Hidden or DocumentCapability.Disabled to restrict inserting fields to the document.