Skip to end of metadata
Go to start of metadata
 

Inserting Fields into a Document

In Aspose.Words the DocumentBuilder.insertField method is used to insert new fields into a document. The first parameter accepts the full field code of the field to be inserted. The second parameter is optional and allows the field result of the field to be set manually. If this is not supplied then the field is updated automatically. You can pass null or empty to this parameter to insert a field with an empty field value.

If your field code has a parameter containing a space then it must be enclosed within speech marks. Otherwise the field in both Microsoft Word and Aspose.Words may not work as expected as the parameter is treated by both as being truncated

Below example shows how to Inserts a merge field into a document using DocumentBuilder.

The same technique is used to insert fields nested within other fields. Below example demonstrates how to insert fields nested within another field using DocumentBuilder.

Finding the Field Code and Field Result

A field which is inserted using DocumentBuilder.insertField returns a Field object. This is a façade class which provides useful methods to quickly find such properties of a field. Note if you are only looking for the names of merge fields in the document then you can instead use the built-in method MailMerge.getFieldNamesBelow example shows how to get names of all merge fields in a document.

Update Fields having Dirty Attribute

The w:dirty is a field-level attribute that will refresh only the field you specify when the document is opened. It tells MS Word to only refresh this field the next time the document is opened. You can use LoadOptions.setUpdateDirtyFields() property to specify whether to update the fields with the dirty attribute. When the value of LoadOptions.setUpdateDirtyFields() is set to true, all fields having true value for Field.IsDirty or FieldChar.IsDirty property are updated on document load. Following example shows how to update fields having dirty attribute.


Inserting Fields using DOM

Inserting Merge Field into a Document using DOM

MERGEFIELD field in Word document can be represented by the FieldMergeField class. You can use FieldMergeField class to perform following operations:

  • Specify the name of merge field
  • Specify the formatting of merge field
  • Specify the text that is between the field separator and field end of merge field
  • Specify the text to be inserted after the merge field if the field is not blank
  • Specify the text to be inserted before the merge field if the field is not blank.

You can download the template file of this example from here.

Inserting Mail Merge Address Block field into a Document using DOM

ADDRESSBLOCK field is used to insert a mail merge address block in Word document. ADDRESSBLOCK field in Word document can be represented by the FieldAddressBlock class. You can use FieldAddressBlock class to perform following operations:

  • Specify whether to include the name of the country/region in field.
  • Specify whether to format the address according to the country/region of the recipient as defined by POST*CODE (Universal Postal Union 2006).
  • Specify the excluded country/region name.
  • Specify the name and address format.
  • Specify the language ID used to format the address.

You can download the template file of this example from here.

Inserting Advance field into a Document without using DocumentBuilder

ADVANCE field is used to offset subsequent text within a line to the left, right, up or down. ADVANCE field in Word document can be represented by the FieldAdvance class. You can use FieldAdvance class to perform following operations:

  • Specify the number of points by which the text that follows the field should be moved vertically from the top edge of the page.
  • Specify the number of points by which the text that follows the field should be moved horizontally from the left edge of the column, frame, or text box.
  • Specify the number of points by which the text that follows the field should be moved left, right, up or down.

Inserting ASK field into a Document without using DocumentBuilder

ASK field is used to prompt the user for text to assign to a Bookmark in Word document. ASK field in Word document can be represented by the FieldAsk class. You can use FieldAsk class to perform following operations:

  • Specify the name of the bookmark.
  • Specify default user response (initial value contained in the prompt window).
  • Specify whether the user response should be received once per a mail merge operation
  • Specify the prompt text (the title of the prompt window).

Inserting AUTHOR field into a Document without using DocumentBuilder

AUTHOR field is used to specify the name of Document's author from the Document properties. AUTHOR field in Word document can be represented by the FieldAuthor class. You can use FieldAuthor class to perform following operations:

Below example shows how to Add a AUTHOR Field using DOM to a Paragraph in Document.

Java

Inserting INCLUDETEXT field into a Document without using DocumentBuilder

The INCLUDETEXT field inserts the text and graphics contained in the document named in the field code. You can insert the entire document or a portion of the document referred to by a bookmark. This field in Word document is represented by INCLUDETEXT. You can use FieldIncludeText class to perform following operations:

  • Specify the bookmark's name of included document. 
  • Specify the location of the document.

For more details, please refer to FieldIncludeText Class API reference. Below example shows how to Add a INCLUDETEXT field using DOM to a Paragraph in Document. 

Inserting TOA field into a Document without using DocumentBuilder

The TOA (Table of Authorities) field builds and inserts a table of authorities. The TOA field collects entries marked by TA (Table of Authorities Entry) fields. Microsoft Office Word inserts the TOA field when you click Insert Table of Authorities in the Table of Authorities group on the References tab. When you view the TOA field in your document, the syntax looks like this:

{ TOA [Switches ] }

Please refer to FieldToa Class API reference. Below example shows how to Add a TOA field using DOM to a Paragraph in Document.

 

Removing a Field

Sometimes it is necessary to remove a field from the document. This may occur when it is to be replaced with a different field type or when the field is no longer needed in the document. For example a TOC field when saving to HTML. A field inserted into the document using DocumentBuilder.insertField returns a Field object which provides a convenience method to easily remove the field from the document. Below example removes a field from the document. You can download the template file of this example from here.

How to Apply Custom Formatting to Field Result

Aspose.Words provides API for custom formatting of field's result. You can implement IFieldResultFormatter interface to control how the field result is formatted. You can apply numeric format switch, i.e. \# "#.##", date/time format switch, i.e. \@ "dd.MM.yyyy", and number format switch, i.e. \* Ordinal. Following code example shows how to apply custom formatting for field's result.

How to evaluate IF condition

If you want to evaluate IF condition after mail merge, you can use FieldIf.EvaluateCondition method that immediately returns the result of expression's evaluation. Below code example shows how to use this method.

Inserting Fields using DocumentBuilder

How to Insert Untyped/Empty Field

If you want to insert untyped/empty fields ({}) just like MS Word allows, you can use DocumentBuilder.InsertField method with parameter FieldType.FieldNone. To insert a field in Word document, you can press “Ctrl + F9” key combination. Below code example shows how to insert empty field in the document.

Insert Compare Field in Word Document

COMPARE field compares two values and returns the numeric value 1 if the comparison is true or 0 if the comparison is false. The following example shows how to add COMPARE fields by using DocumentBuilder to a Word Document:

Insert IF Field in Word Document

IF field can be used to evaluate arguments conditionally. The following example shows how to add IF fields by using DocumentBuilder to a Word Document:

Labels
  • No labels