Working with Index and Tables Fields

Working with Index and Tables Fields

This guide shows how to work with Word’s “Index and Tables” field family — the fields behind a table of contents, an index, a table of figures, and a table of authorities. Each of these is a Field subclass in the Aspose.Words.Fields namespace: FieldToc (table of contents or figures), FieldIndex (index), FieldXE (index entry), FieldToa (table of authorities), FieldTA (table-of-authorities entry, or citation), FieldTC (table-of-contents entry), and FieldRD (referenced document, for building a combined index or TOC across multiple files).

The Field Base Class

Every field class in this family inherits from Field, which exposes Start, Separator, and End (the FieldStart, FieldSeparator, and FieldEnd nodes that bound the field in the run stream), Type (a FieldType value — FieldTOC, FieldIndex, FieldTOA, FieldTOCEntry, FieldIndexEntry, FieldTOAEntry, or FieldRefDoc for this family), Result/DisplayResult (the field’s currently computed text), IsLocked and IsDirty, and the methods GetFieldCode(), Update(), Unlink(), and Remove(). Update() recomputes the field’s result; for a table of contents, that means rebuilding the entry list from the document’s headings or FieldTC markers.

Inserting a Table of Contents

DocumentBuilder.InsertTableOfContents(switches) inserts a FieldToc at the builder’s current position, using a Word field-switch string (for example "\o \"1-3\" \h \z \u") to control which heading levels are included and how the result is formatted — the same switches Word itself writes when you insert a TOC through the UI. Once inserted, FieldToc.UpdatePageNumbers() recomputes the page-number portion of existing entries. FieldToc also exposes properties controlling the TOC’s structure directly: HeadingLevelRange and EntryLevelRange (which outline levels are included), EntryIdentifier (the TC field identifier the TOC should collect, for building multiple TOCs from different FieldTC markers), InsertHyperlinks, PreserveTabs/PreserveLineBreaks, EntrySeparator/SequenceSeparator, BookmarkName, and — for a table of figures rather than a table of contents — TableOfFiguresLabel and CaptionlessTableOfFiguresLabel.

Marking Custom Table of Contents Entries

Not every TOC entry comes from a heading style. FieldTC marks a specific location as a table-of-contents entry independent of paragraph style: FieldTC.Text is the entry text, EntryLevel is the outline level it should appear at, TypeIdentifier links it to a FieldToc.EntryIdentifier when building more than one TOC, and OmitPageNumber suppresses the page number for that entry.

Building an Index

FieldIndex implements the INDEX field, which compiles a document’s FieldXE (index entry) markers into an alphabetical index. FieldXE.Text is the entry text, EntryType groups entries into sub-levels using colon-separated syntax, PageRangeBookmarkName marks a bookmark whose extent becomes a page range in the index rather than a single page number, and IsBold/IsItalic format the resulting page reference. On the FieldIndex side, Heading inserts letter-heading separators (A, B, C…), LetterRange restricts the index to a subset of the alphabet, RunSubentriesOnSameLine controls sub-entry layout, and PageNumberSeparator/PageRangeSeparator/SequenceSeparator/CrossReferenceSeparator control the punctuation between an entry and its page reference. FieldIndexFormat separately enumerates Word’s built-in index visual styles (Template, Classic, Fancy, Modern, Bulleted, Formal, Simple).

Table of Authorities

FieldToa and FieldTA are the authorities equivalent of FieldIndex/FieldXE: FieldTA marks a citation in the text (LongCitation and ShortCitation text, EntryCategory to group it under a heading such as “Cases” or “Statutes”, and IsBold/IsItalic for formatting), and FieldToa compiles those citations into a table, with EntryCategory selecting which category to compile, UseHeading and UsePassim controlling category headings and the “passim” convention for sources cited many times, and PageRangeSeparator/PageNumberListSeparator/SequenceSeparator/EntrySeparator/RemoveEntryFormatting controlling layout.

Referencing Content From Other Documents

FieldRD implements the RD field, which tells a TOC, index, or table of authorities field to include entries from another file when compiling — FieldRD.FileName is the referenced document, and IsPathRelative controls whether that path is resolved relative to the current document.

Tips and Best Practices

• Build the TOC switch string the same way Word does (\o "1-3" \h \z \u) rather than configuring every FieldToc property individually, then adjust only the specific properties you need to change afterward.
• Call FieldToc.UpdatePageNumbers() (or Field.Update()) after content changes so a TOC, index, or table of authorities reflects the current document rather than stale results from when it was inserted.
• Use FieldTC.TypeIdentifier together with FieldToc.EntryIdentifier when a document needs more than one TOC (for example a main TOC and a separate table of figures) built from different sets of entries.
• Set FieldXE.PageRangeBookmarkName (or FieldTA’s equivalent range marking) rather than manually formatting a page range in the entry text, so the index/table stays consistent if content moves.
• Remember that page numbers in this edition’s INDEX/TOC/TOA results evaluate to placeholder values rather than real page numbers, since page layout and pagination are not part of this edition.

Common Issues

FAQ

How do I insert a table of contents programmatically?

Call DocumentBuilder.InsertTableOfContents(switches) with a Word-style switch string, such as "\o \"1-3\" \h \z \u", at the position where the TOC should appear.

How do I mark text as an index entry?

Insert a FieldXE field at that location (for example via DocumentBuilder.InsertField) with its Text property set to the entry text; FieldIndex compiles all FieldXE markers in the document into the index result.

What’s the difference between FieldTC and heading-based TOC entries?

Word’s default TOC behavior collects entries from paragraphs using heading styles. FieldTC lets you mark an arbitrary location as a TOC entry independent of paragraph style, which FieldToc can include via matching EntryIdentifier/TypeIdentifier values.

How do I refresh a TOC or index after the document changes?

Call Update() on the specific field (for example FieldToc.Update(), or FieldToc.UpdatePageNumbers() for page numbers only), or Document.UpdateFields() to refresh every field in the document.

Can I compile a TOC or index across multiple documents?

Yes — insert a FieldRD field pointing at each additional document via FileName; the compiling field (FieldToc, FieldIndex, or FieldToa) includes entries from referenced documents when it is updated.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation