Aspose.Words

How to Update Fields

When a document is loaded, Aspose.Words mimics the behavior of Microsoft Word with the option to automatically update fields is switched off. The behavior can be summarized as follows:

·          When you open/save a document the fields remain intact.

·          You can explicitly update all fields in a document (e.g. rebuild TOC) when you need to.

·          When you print/render to PDF or XPS the fields related to page-numbering in headers/footers are updated.

·          When you execute mail merge all fields are updated automatically.

Update Fields Programmatically

To explicitly update fields in the whole document, simply call Document.UpdateFields.

To update fields contained in part of a document, obtain a Range object and call the Range.UpdateFields method. In Aspose.Words, you can obtain a Range for any node in the document tree, such as Section, HeaderFooter, Paragraph etc using the Node.Range property.

You can update the result of a single field by calling Field.Update.

Automatic Update of Page-Related Fields during Rendering

When you execute conversion of a document to a fixed-page format e.g. to PDF or XPS, then Aspose.Words will automatically update page layout-related fields PAGE, PAGEREF found in headers/footers of the document. This behavior mimics the behavior of Microsoft Word when printing a document.

If you want to update all other fields in the document, then you need to call Document.UpdateFields before rendering the document.

Example UpdateFieldsBeforeRendering

Shows how to update all fields before rendering a document.

[Java]

 

Document doc = new Document(getMyDir() + "Rendering.doc");

 

// This updates all fields in the document.

doc.updateFields();

 

doc.save(getMyDir() + "Rendering.UpdateFields Out.pdf");

 

 

Automatic Field Update during Mail Merge

When you execute a mail merge, all fields in the document will be automatically updated. This is because mail merge is a case of a field update. The program encounters a mail merge field and needs to update its result, which involves grabbing the value from the data source and inserting it into the field. The logic is of course more complicated, for example, when the end of the document/mail merge region is reached but there is still further data to be merged, then the region needs to be duplicated and the new set of fields updated.

Date and Number Formatting in Fields

When Aspose.Words calculates a field result, it often needs to parse a string into a number or date value and also to format it back to a string.

By default Aspose.Words uses the current thread locale to perform parsing and formatting when calculating field values during field update and mail merge. There are also options provided in the form of the FieldOptions class which allows further control over which locale is used during field update.

·          By default the FieldOptions.FieldUpdateCultureSource property is set to FieldUpdateCultureSource.CurrentThread which formats fields using the current thread locale.

·          This property can be set to FieldUpdateCultureSource.FieldCode so the language set from the field code of the field is used for formatting instead.

Formatting using the Current Thread’s Locale

To control the locale used during field calculation, just set the Locale.setDefault property to a locale of your choice before invoking field calculation.

Example ChangeCurrentCulture

Shows how to change the culture used in formatting fields during update.

[Java]

 

// Store the current culture so it can be set back once mail merge is complete.

Locale currentCulture = Locale.getDefault();

// Set to German language so dates and numbers are formatted using this culture during mail merge.

Locale.setDefault(new Locale("de", "DE"));

 

// Execute mail merge

doc.getMailMerge().execute(new String[]{"Date"}, new Object[]{new Date()});

 

// Restore the original culture.

Locale.setDefault(currentCulture);

 

 

Using the current locale to format fields allows a system to easily and consistently control how all fields in the document are formatted during field update.

Formatting using the Locale in the Document

On the other hand, Microsoft Word formats each individual field based off the language of the text found in the field (specifically, the runs from the field code). Sometimes during field update this may be the desired behavior, for example if you have globalized documents containing content made up of many different languages and would like each fields to honor the locale used from the text. Aspose.Words also supports this functionality.

The Document class provides a FieldOptions property which contains members which can be used to control how fields are updated within the document.

Example ChangeFieldUpdateCultureSource

Shows how to specify where the locale for date formatting during field update and mail merge is chosen from.

[Java]

 

// Set the culture used during field update to the culture used by the field.

doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);

doc.getMailMerge().execute(new String[] { "Date2" }, new Object[] { new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01") });