Fields
Fields are a convenient way to show non-static data in the document. In this way, you could present different data to the end-user without actually changing the document content.
This topic contains the following sections:
Field Types
In RadDocument the base class for all fields is CodeBasedField. It is an abstract class that can be inherited from. Some of the implemented and ready-to-use field types are:
DateField: Inserts the current date in one of the specified formats.
PageField: Shows the current page number.
NumPagesField: Shows the number of pages in the document.
MergeField: Used in mail-merge scenarios. You can read more here: Mail Merge.
IncludePictureField: Specifies the URI from which an image must be retrieved.
DocumentVariableField: А field which uses DocumentVariables. More information can be found here: Document Variables.
SequentialField: Tracks the number of tables and figures inserted in the document before a place in the document,so that the InsertCaption() method would use the correct number. Find more here: Captions for tables and Figures.
StyleReferenceField: The type of field that a reference field refers to when a cross-reference to a Heading style is inserted.
ReferenceField: Used to refer to a bookmark or other type of field. It is inserted when a cross-reference to a table or figure caption is added to the document. Find more here: Cross Reference.
PageReferenceField: Used in table of contents in order to be able to navigate to the respective page on Ctrl + Click.
HyperlinkField: Inserted in hyperlinks to store information about the navigation URI.
TCField: Used in table of contents to describe one entry. They include the text of the entry and the page reference field.
AuthorField: The type of field is related to track changes, specifies the name of the user that has modified the document part. Read more here: Track Changes.
CitationField: Inserted when you add a citation to the document.
BibliographyField: Inserted in the document when you want to add information about the bibliographic sources used in the document. Read more here: Bibliographic References.
Display Modes
Fields normally have two modes – Code and Result. When in code mode, they appear as {<FieldTypeName> [<field parameter>] [<switch> <switch parameter>]*}.
For instance, Page Fields appear as { PAGE }, Merge Fields as { MERGEFIELD FirstName }
or { MERGEFIELD FirstName \b "text that will appear before the merge field if it is not empty" }.
In result mode, all fields get evaluated depending on some conditions – the place in the document where they appear in the case of page fields, the current mail merge record for merge fields, etc.
MergeFields have one additional mode – DisplayName that shows the property path they use in brackets of the type <<[PropertyPathHere]>>. Furthermore, there are specific methods and commands of the editor that change the display mode of merge fields or even remove them from the document altogether, replacing them with the ResultFragment. More information on this topic can be found in the Mail Merge article.
Inserting a Field
Inserting any type of field in the document of an editor can be done with the InsertField() method.
Insert a page field:
this.radRichTextEditor1.InsertField(new PageField());
Me.radRichTextEditor1.InsertField(New PageField())
Update of a field can be triggered from the context menu or using the UpdateField() method of RadRichTextEditor by passing the FieldRangeStart of the field as a parameter.
Update a field:
this.radRichTextEditor1.UpdateField(new FieldRangeStart());
Me.radRichTextEditor1.UpdateField(New FieldRangeStart())
You can also update all fields in the current document with the UpdateAllFields() method of RadRichTextEditor.
Fields Update Priority
All field types in the context of RadDocument have an update priority which determines when they should be updated when the UpdateAllFields() method is invoked. Most fields have the default value 0. Changing it is needed in case a field depends on the evaluated value of another field to be properly evaluated.
Priority can be specified through the FieldsUpdateManager static class. The following code snippet shows how to set higher priority for a specific field type, causing all fields of this type to be updated before the rest of the fields when calling UpdateAllField():
FieldsUpdateManager.RegisterFieldUpdatePriority(typeof(ReferenceField), 1000);
FieldsUpdateManager.RegisterFieldUpdatePriority(GetType(ReferenceField), 1000)
Having many different values for field priory is not recommended and may lead to performance degradation of the UpdateAllFields() method. The reason for this is that all fields with the same priority are updated in a batch update. Having more priority groups leads to execution of more batch updates.