Fields

Overview

This guide shows how to insert, update and read Word fields with Aspose.Words FOSS for Java. A Word field is an instruction in the text, such as a document property, a hyperlink or a page number, whose result Word computes. DocumentBuilder.insertField inserts a field from a field code, Field.update or Document.updateFields computes the results, and Field.getFieldCode, getResult and getType read a field back. This page inserts a DOCPROPERTY field and reads its result, and shows what happens to fields that need page layout. Both examples were compiled and run against the published package on Java 8, 17 and 21.


Prerequisites

RequirementDetail
Java8 or later
DependencyThe package from Installation
Importimport com.aspose.words.*;
CodeThe examples are statements. Put them in a method that declares throws Exception.

Insert a Field and Read Its Result

The example sets the built-in title, inserts a field with the code DOCPROPERTY Title and calls update. The field code read back as DOCPROPERTY Title, the result as the title, and getType equalled FieldType.FIELD_DOC_PROPERTY.

import com.aspose.words.*;

Document doc = new Document();
doc.getBuiltInDocumentProperties().setTitle("Quarterly Report");

DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Document title: ");
Field field = builder.insertField("DOCPROPERTY Title");

field.update();
System.out.println("Field code: " + field.getFieldCode().trim());
System.out.println("Field result: " + field.getResult());
System.out.println("Field type is DOCPROPERTY: " + (field.getType() == FieldType.FIELD_DOC_PROPERTY));

The program printed:

Field code: DOCPROPERTY Title
Field result: Quarterly Report
Field type is DOCPROPERTY: true

Fields That Need Page Layout

PAGE and NUMPAGES results depend on page layout, which this edition does not do. After doc.updateFields() the example printed empty results for both fields: the field is in the document, and its result stays empty.

import com.aspose.words.*;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Page ");
Field page = builder.insertField("PAGE");
builder.write(" of ");
Field pages = builder.insertField("NUMPAGES");

doc.updateFields();
// Page numbers need page layout, which this edition does not do: the results stay empty.
System.out.println("PAGE result: [" + page.getResult() + "]");
System.out.println("NUMPAGES result: [" + pages.getResult() + "]");

The program printed:

PAGE result: []
NUMPAGES result: []

Tips and Best Practices

  • Call update on one field, or Document.updateFields for the whole document, before you read getResult.
  • getFieldCode returns the text between the field start and the field separator.
  • Use Range.getFields to list the fields of a document.

Common Issues

IssueCauseFix
The compiler reports cannot find symbol for Document.The com.aspose.words package is not imported.Add import com.aspose.words.*;.
The compiler reports an unreported exception.The Document constructors, Document.save and some other methods declare throws Exception.Declare it on the calling method or catch it.
The result of a PAGE or NUMPAGES field is empty.Page numbers need page layout, which this edition does not do.Do not depend on layout-dependent field results.
Updating a NOTEREF field gives Error! Bookmark not defined.Updating a NOTEREF field does not work in this edition (tested on Java 8, 17 and 21).Write the reference text yourself.

FAQ

Which field results can I read?

The DOCPROPERTY result in the example is available after update. Results that depend on page layout stay empty, and NOTEREF gives an error. In a test on Java 17 a SYMBOL field had an empty result and a NUMWORDS field the result 0, so test every field type you rely on.

How do I update every field?

Call Document.updateFields, which updates the values of fields in the whole document.


API Reference Summary

Class / MethodDescription
FieldRepresents a Microsoft Word document field.
FieldTypeSpecifies Microsoft Word field types.
DocumentBuilder.insertField(fieldCode)Inserts a Word field into a document and optionally updates the field result.
Document.updateFields()Updates the values of fields in the whole document.

Related Guides

See Also