Fields in a document are like placeholders where some useful data can be inserted. For example, a field can be a page reference, formula or a mail merge field. A field in a Microsoft Word document consists of a field code and field result. The field code is an instruction about how the field result needs to be updated or calculated. An application that processes a document and encounters a field might have the functionality to interpret the instructions contained in the field code and update the field result with a new value. This is called field update.
Usually, a field, when inserted in Microsoft Word, already contains an up to date value. For example, if the field is a formula or a page number, it will contain a correct calculated value for the given version of the document. But if you have an application that generates or modifies a document with fields, for example combines two documents or populates with data, then for the document to be useful, all fields should ideally be updated.
Fields in Microsoft Word documents are complex. There are over 50 field types (each needs its own result calculation procedure), formulas and expressions, bookmarks and references, functions and various switches. Fields can also be nested.
Aspose.Words is a class library designed for server-side processing of Microsoft Word documents and supports fields in the following ways:
· All fields in a document are preserved during open/save and conversions.
· It is possible to update results of some of the most popular fields.
Calculation of the following fields is supported in the current version of Aspose.Words:
· = (formula field)
· ADDRESSBLOCK
· AUTHOR
· COMPARE
· CREATEDATE
· DATE
· DOCPROPERTY
· DOCVARIABLE
· GREETINGLINE
· IF
· INCLUDETEXT
· MERGEFIELD
· MERGEREC
· MERGESEQ
· NEXT
· NEXTIF
· NUMPAGES
· PAGE
· PAGEREF
· REF
· SECTION
· SECTIONPAGES
· SEQ
· SET
· STYLEREF
· TIME
· TITLE
· TOA
· TOC (including TOT and TOF)
· TC
Aspose.Words follows the way Microsoft Word processes fields and as a result it correctly handles:
· Nested fields
IF { =OR({ COMPARE { =2.5 +PRODUCT(3,5 ,8.4) } > 4}, { =2/2 }) } = 1 "Credit not acceptable" "Credit acceptable"
· Field argument can be a result of a nested field.
· Fields can be nested within a field code as well as in the field result.
· Spaces/no spaces, quotes/no quotes, escape characters in fields etc
MERGEFIELD \f"Text after""Field \n\ame with \" and \\ and \*"\bTextBefor\e
· Fields that span across multiple paragraphs.
Aspose.Words provides a very serious implementation of the formula engine and supports the following:
· Arithmetic and logical operators
=(54+4*(6-77)-(5))+(-6-5)/4/5
· Functions
=ABS(-01.4)+2.645/(5.6^3.5)+776457 \# "#,##0"
· References to bookmarks
=IF(C>4, 5,ABS(A)*.76) +3.85
· Number formatting switches
=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.
Just 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
Aspose.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:
· Mail merge field switches
MERGEFIELD FirstName \* FirstCap \b "Mr. "
· Nested merge fields in a formula
IF { MERGEFIELD Value1 } >= { MERGEFIELD Value2 } True False
· Calculate the name of the merge field at runtime
MERGEFIELD { IF { MERGEFIELD Value1 } >= { MERGEFIELD Value2 } FirstName"LastName" }
· Conditional move to next record in the data source
NEXTIF { MERGEFIELD Value1 } <= { =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:
· \@ - date and time formatting
· \# - number formatting
· \* Caps
· \* FirstCap
· \* Lower
· \* Upper
· \* CHARFORMAT – format result according to the first character of the field code.
· \* MERGEFORMAT – format result according to how the old result is formatted.