Insert Fields

There are several different ways to insert fields into a document:

• using DocumentBuilder
• using FieldBuilder
• using Aspose.Words Document Object Model (DOM)

In this article, we will look at each way in more detail and analyze how to insert certain fields using these options.

Inserting Fields into a Document using DocumentBuilder

In Aspose.Words the 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 you are not sure about the particular field code syntax, create the field in Microsoft Word first and switch to see its field code.

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.

The following code example shows how to inserts a merge field into a document using DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(InsertField.class);

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD MyFieldName \\* MERGEFORMAT");

doc.save(dataDir + "output.docx");

The same technique is used to insert fields nested within other fields.

The following code example demonstrates how to insert fields nested within another field using DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

for (int i = 0; i < 5; i++)
    builder.insertBreak(BreakType.PAGE_BREAK);

builder.moveToHeaderFooter(HeaderFooterType.FOOTER_PRIMARY);

// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
Field field = builder.insertField("IF ");
builder.moveTo(field.getSeparator());
builder.insertField("PAGE");
builder.write(" <> ");
builder.insertField("NUMPAGES");
builder.write(" \"See Next Page\" \"Last Page\" ");

field.update();

doc.save(getArtifactsDir() + "WorkingWithFields.InsertNestedFields.docx");

Specify Locale at Field Level

A language identifier is a standard international numeric abbreviation for the language in a country or geographical region. With Aspose.Words, you can specify the Locale at the field level using the LocaleId property, which gets or sets the field’s locale ID.

The following code example shows how to use this option:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
DocumentBuilder builder = new DocumentBuilder();

Field field = builder.insertField(FieldType.FIELD_DATE, true);
field.setLocaleId(1049);

builder.getDocument().save(getArtifactsDir() + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

Insert Untyped/Empty Field

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

The following code example shows how to insert an empty field into the document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

FieldUnknown field = (FieldUnknown) builder.insertField(FieldType.FIELD_NONE, false);

doc.save(getArtifactsDir() + "WorkingWithFields.InsertFieldNone.docx");

Insert COMPARE Field

The 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 code example shows how to add COMPARE fields using DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

FieldCompare field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("3");
field.setComparisonOperator("<");
field.setRightExpression("2");
field.update();

builder.writeln();

field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.COMPARE.docx");

Insert IF Field

The IF field can be used to evaluate arguments conditionally.

The following code example shows how to add IF fields using DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.write("Statement 1: ");
FieldIf field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("0");
field.setComparisonOperator("=");
field.setRightExpression("1");

// The IF field will display a string from either its "TrueText" property,
// or its "FalseText" property, depending on the truth of the statement that we have constructed.
field.setTrueText("True");
field.setFalseText("False");
field.update();

builder.write("\nStatement 2: ");
field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.setTrueText("True");
field.setFalseText("False");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.IF.docx");

Inserting Fields into a Document using FieldBuilder

The alternative way to insert fields in Aspose.Words is the FieldBuilder class. It provides fluent interface to specify field switches and argument values as text, nodes or even nested fields.

The following code example shows how to insert a field into a document using FieldBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

FieldBuilder firstName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
firstName.addArgument("firstname");
FieldBuilder lastName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
lastName.addArgument("lastname");

FieldArgumentBuilder firstnameArgumentBuilder = new FieldArgumentBuilder();
firstnameArgumentBuilder.addText("Firstname: ");
firstnameArgumentBuilder.addField(firstName);

FieldArgumentBuilder lastnameArgumentBuilder = new FieldArgumentBuilder();
lastnameArgumentBuilder.addText("Lastname: ");
lastnameArgumentBuilder.addField(lastName);

// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
fieldBuilder.addArgument("left expression");
fieldBuilder.addArgument("=");
fieldBuilder.addArgument("right expression");
fieldBuilder.addArgument(firstnameArgumentBuilder);
fieldBuilder.addArgument(lastnameArgumentBuilder);

// Insert IF field in exact location
Field field = fieldBuilder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
field.update();

doc.save(getArtifactsDir() + "Field.InsertFieldUsingFieldBuilder.docx");

Inserting Fields using DOM

You can also insert various types of fields using Aspose.Words Document Object Model (DOM). In this section, we will look at a few examples.

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 the following operations:

• specify the name of the merge field
• specify the formatting of the merge field
• specify the text that is between the field separator and field end of the 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

For more details, see the FieldMergeField class API.

The following code example shows how to add the MERGE field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);
builder.moveTo(para);

// We want to insert a merge field like this:
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
FieldMergeField field = (FieldMergeField) builder.insertField(FieldType.FIELD_MERGE_FIELD, false);

// { " MERGEFIELD Test1" }
field.setFieldName("Test1");
// { " MERGEFIELD Test1 \\b Test2" }
field.setTextBefore("Test2");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field.setTextAfter("Test3");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" }
field.isMapped(true);
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
field.isVerticalFormatting(true);

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertMergeFieldUsingDOM.docx");

Inserting Mail Merge ADDRESSBLOCK field into a Document using DOM

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

• specify whether to include the name of the country/region in the 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

For more details, see the FieldAddressBlock class API.

The following code example shows how to add the Mail Merge ADDRESSBLOCK Field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);
builder.moveTo(para);

// We want to insert a mail merge address block like this:
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
FieldAddressBlock field = (FieldAddressBlock) builder.insertField(FieldType.FIELD_ADDRESS_BLOCK, false);

// { ADDRESSBLOCK \\c 1" }
field.setIncludeCountryOrRegionName("1");
// { ADDRESSBLOCK \\c 1 \\d" }
field.setFormatAddressOnCountryOrRegion(true);
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field.setExcludedCountryOrRegionName("Test2");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field.setNameAndAddressFormat("Test3");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field.setLanguageId("Test 4");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

Inserting ADVANCE field into a Document without using DocumentBuilder

The 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 the 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

For more details, see the FieldAdvance class API.

The following code example shows how to add the ADVANCE Field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an Advance field like this:
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
FieldAdvance field = (FieldAdvance) para.appendField(FieldType.FIELD_ADVANCE, false);

// { ADVANCE \\d 10 " }
field.setDownOffset("10");
// { ADVANCE \\d 10 \\l 10 }
field.setLeftOffset("10");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field.setRightOffset("-3.3");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field.setUpOffset("0");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field.setHorizontalPosition("100");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field.setVerticalPosition("100");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.docx");

Inserting ASK field into a Document without using DocumentBuilder

The 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)

For more details, see the FieldAsk class API.

The following code example shows how to add the ASK Field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an Ask field like this:
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
FieldAsk field = (FieldAsk) para.appendField(FieldType.FIELD_ASK, false);

// { ASK \"Test 1\" " }
field.setBookmarkName("Test 1");
// { ASK \"Test 1\" Test2 }
field.setPromptText("Test2");
// { ASK \"Test 1\" Test2 \\d Test3 }
field.setDefaultResponse("Test3");
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field.setPromptOnceOnMailMerge(true);

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.docx");

Inserting AUTHOR field into a Document without using DocumentBuilder

The 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:

• specify the document author’s name

For more details, see the FieldAuthor class API.

The following code example shows how to add the AUTHOR Field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

// We want to insert an AUTHOR field like this:
// { AUTHOR Test1 }
FieldAuthor field = (FieldAuthor) para.appendField(FieldType.FIELD_AUTHOR, false);
field.setAuthorName("Test1"); // { AUTHOR Test1 }

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAuthorField.docx");

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, see the FieldIncludeText class API.

The following code example shows how to add the INCLUDETEXT field using DOM to a paragraph in a document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

Paragraph para = new Paragraph(doc);

// We want to insert an INCLUDETEXT field like this:
// { INCLUDETEXT  "file path" }
FieldIncludeText fieldIncludeText = (FieldIncludeText) para.appendField(FieldType.FIELD_INCLUDE_TEXT, false);
fieldIncludeText.setBookmarkName("bookmark");
fieldIncludeText.setSourceFullName(getMyDir() + "IncludeText.docx");

doc.getFirstSection().getBody().appendChild(para);

fieldIncludeText.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

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 ] }

For more details, see the FieldToa class API.

The following code example shows how to add the TOA field using DOM to a paragraph in a document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
Paragraph para = new Paragraph(doc);

// We want to insert TA and TOA fields like this:
// { TA  \c 1 \l "Value 0" }
// { TOA  \c 1 }
FieldTA fieldTA = (FieldTA) para.appendField(FieldType.FIELD_TOA_ENTRY, false);
fieldTA.setEntryCategory("1");
fieldTA.setLongCitation("Value 0");

doc.getFirstSection().getBody().appendChild(para);

para = new Paragraph(doc);

FieldToa fieldToa = (FieldToa) para.appendField(FieldType.FIELD_TOA, false);
fieldToa.setEntryCategory("1");
doc.getFirstSection().getBody().appendChild(para);

fieldToa.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");