Analyzing your prompt, please hold on...
An error occurred while retrieving the results. Please refresh the page and try again.
Aspose.Words is a class library designed for server-side processing of Microsoft Word documents and supports fields in the following ways:
In this article, we will learn more about field structure, the fields supported in Aspose.Words, and details of working with such fields.
A field consists of:
The content which makes up the field code is stored as Run nodes between the FieldStart and FieldSeparator. The field result is stored between the FieldSeparator and FieldEnd nodes and can be made up of various types of content. Normally the field result contains just text made up of Run nodes, however it is possible for the FieldEnd node to be located in a completely different paragraph, and thus making the field result comprised of block level nodes such as Table and Paragraph nodes as well.
Here is a view of how a field is stored in Aspose.Words by using the “DocumentExplorer” example which can be found on Github.
When a document is loaded into Aspose.Words, the fields of the document are loaded into the Aspose.Words Document Object Model as a set of separate components (nodes). A single field is loaded as a collection of FieldStart, FieldSeparator and FieldEnd nodes along with the content in between these nodes. If a field does not have a field result then there will be no FieldSeparator node. All of these nodes are always found inline (as children of Paragraph or SmartTag.
In Aspose.Words each of the FieldXXX nodes derives from FieldChar. This class provides a property to check the type of field represented by the specified node through the FieldType property. For example FieldType.FieldMergeField represents a merge field in the document.
There are some particular fields that exist in a Word document that are not imported into Aspose.Words as a collection of FieldXXX nodes. For instance, LINK
field and INCLUDEPICTURE
field are imported into Aspose.Words as a Shape object. This object provides properties to work with the image data normally stored in these fields. To import INCLUDEPICTURE
field as FieldXXX nodes the PreserveIncludePictureField option must be specified as true.
Form fields are also imported into Aspose.Words as their own special class. The FormField class represents a form field in a Word document and provides additional methods that are particular to a form field.
Calculation of the following fields is supported in the current version of Aspose.Words:
ADDRESSBLOCK
ASK
AUTHOR
AUTONUM
AUTONUMLGL
AUTONUMOUT
AUTOTEXT
BARCODE
COMMENTS
COMPARE
CREATEDATE
DATABASE
DATE
DISPLAYBARCODE
DOCPROPERTY
DOCVARIABLE
EDITTIME
EQ
FILENAME
FILESIZE
FILLIN
FORMCHECKBOX
FORMDROPDOWN
FORMTEXT
GLOSSARY
GOTOBUTTON
GREETINGLINE
HYPERLINK
IF
IMPORT
INCLUDE
INCLUDEPICTURE
INCLUDETEXT
INDEX
INFO
KEYWORDS
LASTSAVEDBY
LISTNUM
MACROBUTTON
MERGEBARCODE
MERGEFIELD
MERGEREC
MERGESEQ
NEXT
NEXTIF
NOTEREF
NUMCHARS
NUMPAGES
NUMWORDS
PAGE
PAGEREF
PRINTDATE
QUOTE
REF
REVNUM
SAVEDATE
SECTION
SECTIONPAGES
SEQ
SET
SHAPE
SKIPIF
STYLEREF
SUBJECT
SYMBOL
TEMPLATE
TIME
TITLE
TOA
TOC
USERADDRESS
USERINITIALS
USERNAME
Aspose.Words follows the way Microsoft Word processes fields and as a result it correctly handles:
IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
MERGEFIELD \f"Text after""Field \n\ame with \" and \\\ and \\\*"\bTextBefor\e
Aspose.Words provides a very serious implementation of the formula engine and supports the following:
=(54+4*(6-77)-(5))+(-6-5)/4/5
=ABS(-01.4)+2.645/(5.6^3.5)+776457 \\\# "#,##0"
=IF(C>4, 5,ABS(A)*.76) +3.85
=00000000 \\\# "$#,##0.00;($#,##0.00)"
The following functions in expressions are supported: ABS
, AND
, AVERAGE
, COUNT
, DEFINED
, FALSE
, IF
, INT
, MAX
, MIN
, MOD
, NOT
, OR
, PRODUCT
, ROUND
, SIGN
, SUM
, TRUE.
IF
and COMPARE
FieldsJust some of the IF
expressions that Aspose.Words can easily calculate should give you an idea of how powerful this feature is:
IF 3 > 5.7^4+MAX(4,3) True False
IF "abcd" > "abc" True False
IF "?ab*" = "1abdsg" True False
IF 4 = "2*2" True False
COMPARE 3+5/34 < 4.6/3/2
DATE
and TIME
FieldsAspose.Words supports all date and time formatting switches available in Microsoft Word, some examples are:
DATE @ "d-MMM-yy"
DATE @ "d/MM/yyyy h:mm am/pm
Aspose.Words imposes no limit on the complexity of Mail Merge fields in your documents and supports nested IF
and formula fields and can even calculate the merge field’s name using a formula.
Some examples of Mail Merge fields that Aspose.Words supports:
MERGEFIELD FirstName \\\\\\\\* FirstCap \b "Mr. "
IF {
MERGEFIELDValue1 } >= {
MERGEFIELD Value2 } True False
MERGEFIELD {
IF{
MERGEFIELDValue1 } >= {
MERGEFIELD Value2 } FirstName"LastName" }
NEXTIF {
MERGEFIELDValue1 } <= { =IF(-2.45 >= 6*{
MERGEFIELD Value2 }, 2, -.45) }
A field in a document can have formatting switches that specify how the resulting value should be formatted. Aspose.Words supports the following format switches:
When Aspose.Words calculates a field result, it often needs to parse a string into a number or date value and also to format it back to a string.By default Aspose.Words uses the current thread culture to perform parsing and formatting when calculating field values during field update and mail merge. There are also options provided in the form of the FieldOptions class which allows further control over which culture is used during field update.
To control the culture used during field calculation, just set the Thread.CurrentThread.CurrentCulture property to a culture of your choice before invoking field calculation.
The following code example shows how to change the culture used in formatting fields during update:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git. | |
Document doc = new Document(); | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
builder.InsertField("MERGEFIELD Date"); | |
// Store the current culture so it can be set back once mail merge is complete. | |
CultureInfo currentCulture = Thread.CurrentThread.CurrentCulture; | |
// Set to German language so dates and numbers are formatted using this culture during mail merge. | |
Thread.CurrentThread.CurrentCulture = new CultureInfo("de-DE"); | |
doc.MailMerge.Execute(new[] { "Date" }, new object[] { DateTime.Now }); | |
Thread.CurrentThread.CurrentCulture = currentCulture; | |
doc.Save(ArtifactsDir + "WorkingWithFields.ChangeLocale.docx"); |
Using the current culture to format fields allows a system to easily and consistently control how all fields in the document are formatted during field update.
On the other hand, Microsoft Word formats each individual field based off the language of the text found in the field (specifically, the runs from the field code). Sometimes during field update this may be the desired behavior, for example if you have globalized documents containing content made up of many different languages and would like each fields to honor the locale used from the text. Aspose.Words also supports this functionality.
The Document class provides a FieldOptions property which contains members which can be used to control how fields are updated within the document.
The following code example shows how to specify where the culture used for date formatting during field update and Mail Merge is chosen from:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git. | |
Document doc = new Document(); | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// Insert content with German locale. | |
builder.Font.LocaleId = 1031; | |
builder.InsertField("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\""); | |
builder.Write(" - "); | |
builder.InsertField("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\""); | |
// Shows how to specify where the culture used for date formatting during field update and mail merge is chosen from | |
// set the culture used during field update to the culture used by the field. | |
doc.FieldOptions.FieldUpdateCultureSource = FieldUpdateCultureSource.FieldCode; | |
doc.MailMerge.Execute(new string[] { "Date2" }, new object[] { new DateTime(2011, 1, 01) }); | |
doc.Save(ArtifactsDir + "WorkingWithFields.ChangeFieldUpdateCultureSource.docx"); |
Analyzing your prompt, please hold on...
An error occurred while retrieving the results. Please refresh the page and try again.