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
| Requirement | Detail |
|---|---|
| Java | 8 or later |
| Dependency | The package from Installation |
| Import | import com.aspose.words.*; |
| Code | The 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: trueFields 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
updateon one field, orDocument.updateFieldsfor the whole document, before you readgetResult. getFieldCodereturns the text between the field start and the field separator.- Use
Range.getFieldsto list the fields of a document.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| 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 / Method | Description |
|---|---|
Field | Represents a Microsoft Word document field. |
FieldType | Specifies 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
- Document Properties
- Bookmarks
- Footnotes and Endnotes
- How to Add and Remove Hyperlink Fields in a Word Document in Java (knowledge base)