Document Automation Fields (IF, COMPARE, MACROBUTTON, and More)

Document Automation Fields (IF, COMPARE, and More)

This guide shows how to work with Word’s document-automation field family in Aspose.Words FOSS for .NET – fields that drive conditional text, store document-scoped variables, and wire up macros, navigation, and print behavior, rather than simply displaying a computed value. Each is a Field subclass in the Aspose.Words.Fields namespace: FieldIf, FieldCompare, FieldDocVariable, FieldGoToButton, FieldMacroButton, and FieldPrint. All of them inherit the core Field members described in Working with Fields – GetFieldCode(), Update(), Remove(), Unlink(), Start/Separator/End, Result, and Format – this page covers what is specific to each.

Conditional Text with FieldIf

FieldIf implements the IF field. LeftExpression, ComparisonOperator, and RightExpression describe the condition – the same three-part shape used by IComparisonExpressionEvaluator (see Working with Fields) – and TrueText / FalseText hold the two possible results. Call EvaluateCondition() to evaluate the condition directly; it returns a FieldIfComparisonResult value: True, False, or Error.

Comparing Values with FieldCompare

FieldCompare implements the COMPARE field. Like FieldIf, it exposes LeftExpression, ComparisonOperator, and RightExpression to describe the comparison, but produces a boolean-style result rather than switching between two text alternatives.

Document Variables with FieldDocVariable

FieldDocVariable implements the DOCVARIABLE field, reading a named document-scoped variable through its VariableName property.

Buttons: FieldGoToButton and FieldMacroButton

FieldGoToButton implements the GOTOBUTTON field: Location names the bookmark, page, or other destination to jump to, and DisplayText is the label shown in the document. FieldMacroButton implements the MACROBUTTON field: MacroName names the macro to run and DisplayText is the label. Both FieldIf and FieldMacroButton additionally implement IMergeFieldSurrogate, the interface Word’s mail-merge-aware fields use to mark themselves as substitutable content.

Print Instructions with FieldPrint

FieldPrint implements the PRINT field: PrinterInstructions and PostScriptGroup hold printer-specific instructions embedded directly in the document.

Tips and Best Practices

• Use FieldIf.EvaluateCondition() to read a condition’s outcome (FieldIfComparisonResult) without needing to parse TrueText/FalseText yourself.
• FieldCompare and FieldIf share the same LeftExpression/ComparisonOperator/ RightExpression shape – code that builds or inspects one comparison expression can be reused across both field types.
• Remember these are all Field subclasses: GetFieldCode(), Update(), Remove(), and Unlink() from Working with Fields apply exactly the same way here.

Common Issues

FAQ

How do I read the result of a conditional IF field?

Call FieldIf.EvaluateCondition() for the raw FieldIfComparisonResult, or read TrueText / FalseText for the two literal text alternatives the field switches between.

What’s the difference between FieldIf and FieldCompare?

FieldIf (the IF field) switches between TrueText and FalseText based on its condition. FieldCompare (the COMPARE field) shares the same comparison shape but produces a boolean-style result rather than alternative text.

How do I read a document variable’s name from a DOCVARIABLE field?

Read FieldDocVariable.VariableName.

How do I find the destination of a GOTOBUTTON field?

Read FieldGoToButton.Location; DisplayText gives the label shown for the button in the document.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation