FieldToc class

Implements the TOC field. To learn more, visit the Working with Fields documentation article.

Remarks

Builds a table of contents (which can also be a table of figures) using the entries specified by TC fields, their heading levels, and specified styles, and inserts that table at this place in the document.

Inheritance: FieldToc → Field

Constructors

Name	Description
FieldToc()	The default constructor.

Properties

Name	Description
bookmark_name	Gets or sets the name of the bookmark that marks the portion of the document used to build the table.
captionless_table_of_figures_label	Gets or sets the name of the sequence identifier used when building a table of figures that does not include caption’s label and number.
custom_styles	Gets or sets a list of styles other than the built-in heading styles to include in the table of contents.
display_result	Gets the text that represents the displayed field result. (Inherited from Field)
end	Gets the node that represents the field end. (Inherited from Field)
entry_identifier	Gets or sets a string that should match type identifiers of TC fields being included.
entry_level_range	Gets or sets a range of levels of the table of contents entries to be included.
entry_separator	Gets or sets a sequence of characters that separate an entry and its page number.
format	Gets a FieldFormat object that provides typed access to field’s formatting. (Inherited from Field)
heading_level_range	Gets or sets a range of heading levels to include.
hide_in_web_layout	Gets or sets whether to hide tab leader and page numbers in Web layout view.
insert_hyperlinks	Gets or sets whether to make the table of contents entries hyperlinks.
is_dirty	Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document. (Inherited from Field)
is_locked	Gets or sets whether the field is locked (should not recalculate its result). (Inherited from Field)
locale_id	Gets or sets the LCID of the field. (Inherited from Field)
page_number_omitting_level_range	Gets or sets a range of levels of the table of contents entries from which to omits page numbers.
prefixed_sequence_identifier	Gets or sets the identifier of a sequence for which a prefix should be added to the entry’s page number.
preserve_line_breaks	Gets or sets whether to preserve newline characters within table entries.
preserve_tabs	Gets or sets whether to preserve tab entries within table entries.
result	Gets or sets text that is between the field separator and field end. (Inherited from Field)
separator	Gets the node that represents the field separator. Can be `None`. (Inherited from Field)
sequence_separator	Gets or sets the character sequence that is used to separate sequence numbers and page numbers.
start	Gets the node that represents the start of the field. (Inherited from Field)
table_of_figures_label	Gets or sets the name of the sequence identifier used when building a table of figures.
type	Gets the Microsoft Word field type. (Inherited from Field)
use_paragraph_outline_level	Gets or sets whether to use the applied paragraph outline level.

Methods

Name	Description
get_field_code()	Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included. (Inherited from Field)
get_field_code(include_child_field_codes)	Returns text between field start and field separator (or field end if there is no separator). (Inherited from Field)
remove()	Removes the field from the document. Returns a node right after the field. If the field’s end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns `None`. (Inherited from Field)
unlink()	Performs the field unlink. (Inherited from Field)
update()	Performs the field update. Throws if the field is being updated already. (Inherited from Field)
update(ignore_merge_format)	Performs a field update. Throws if the field is being updated already. (Inherited from Field)
update_page_numbers()	Updates the page numbers for items in this table of contents.

Examples

Shows how to populate a TOC field with entries using SEQ fields.

doc = aw.Document()
builder = aw.DocumentBuilder(doc=doc)
# A TOC field can create an entry in its table of contents for each SEQ field found in the document.
# Each entry contains the paragraph that includes the SEQ field and the page's number that the field appears on.
field_toc = builder.insert_field(field_type=aw.fields.FieldType.FIELD_TOC, update_field=True).as_field_toc()
# SEQ fields display a count that increments at each SEQ field.
# These fields also maintain separate counts for each unique named sequence
# identified by the SEQ field's "SequenceIdentifier" property.
# Use the "TableOfFiguresLabel" property to name a main sequence for the TOC.
# Now, this TOC will only create entries out of SEQ fields with their "SequenceIdentifier" set to "MySequence".
field_toc.table_of_figures_label = 'MySequence'
# We can name another SEQ field sequence in the "PrefixedSequenceIdentifier" property.
# SEQ fields from this prefix sequence will not create TOC entries.
# Every TOC entry created from a main sequence SEQ field will now also display the count that
# the prefix sequence is currently on at the primary sequence SEQ field that made the entry.
field_toc.prefixed_sequence_identifier = 'PrefixSequence'
# Each TOC entry will display the prefix sequence count immediately to the left
# of the page number that the main sequence SEQ field appears on.
# We can specify a custom separator that will appear between these two numbers.
field_toc.sequence_separator = '>'
self.assertEqual(' TOC  \\c MySequence \\s PrefixSequence \\d >', field_toc.get_field_code())
builder.insert_break(aw.BreakType.PAGE_BREAK)
# There are two ways of using SEQ fields to populate this TOC.
# 1 -  Inserting a SEQ field that belongs to the TOC's prefix sequence:
# This field will increment the SEQ sequence count for the "PrefixSequence" by 1.
# Since this field does not belong to the main sequence identified
# by the "TableOfFiguresLabel" property of the TOC, it will not appear as an entry.
field_seq = builder.insert_field(field_type=aw.fields.FieldType.FIELD_SEQUENCE, update_field=True).as_field_seq()
field_seq.sequence_identifier = 'PrefixSequence'
builder.insert_paragraph()
self.assertEqual(' SEQ  PrefixSequence', field_seq.get_field_code())
# 2 -  Inserting a SEQ field that belongs to the TOC's main sequence:
# This SEQ field will create an entry in the TOC.
# The TOC entry will contain the paragraph that the SEQ field is in and the number of the page that it appears on.
# This entry will also display the count that the prefix sequence is currently at,
# separated from the page number by the value in the TOC's SeqenceSeparator property.
# The "PrefixSequence" count is at 1, this main sequence SEQ field is on page 2,
# and the separator is ">", so entry will display "1>2".
builder.write('First TOC entry, MySequence #')
field_seq = builder.insert_field(field_type=aw.fields.FieldType.FIELD_SEQUENCE, update_field=True).as_field_seq()
field_seq.sequence_identifier = 'MySequence'
self.assertEqual(' SEQ  MySequence', field_seq.get_field_code())
# Insert a page, advance the prefix sequence by 2, and insert a SEQ field to create a TOC entry afterwards.
# The prefix sequence is now at 2, and the main sequence SEQ field is on page 3,
# so the TOC entry will display "2>3" at its page count.
builder.insert_break(aw.BreakType.PAGE_BREAK)
field_seq = builder.insert_field(field_type=aw.fields.FieldType.FIELD_SEQUENCE, update_field=True).as_field_seq()
field_seq.sequence_identifier = 'PrefixSequence'
builder.insert_paragraph()
field_seq = builder.insert_field(field_type=aw.fields.FieldType.FIELD_SEQUENCE, update_field=True).as_field_seq()
builder.write('Second TOC entry, MySequence #')
field_seq.sequence_identifier = 'MySequence'
doc.update_fields()
doc.save(file_name=ARTIFACTS_DIR + 'Field.TOC.SEQ.docx')

Shows how to insert a TOC, and populate it with entries based on heading styles.

def field_toc():
    doc = aw.Document()
    builder = aw.DocumentBuilder(doc)
    builder.start_bookmark('MyBookmark')
    # Insert a TOC field, which will compile all headings into a table of contents.
    # For each heading, this field will create a line with the text in that heading style to the left,
    # and the page the heading appears on to the right.
    field = builder.insert_field(aw.fields.FieldType.FIELD_TOC, True).as_field_toc()
    # Use the "bookmark_name" property to only list headings
    # that appear within the bounds of a bookmark with the "MyBookmark" name.
    field.bookmark_name = 'MyBookmark'
    # Text with a built-in heading style, such as "Heading 1", applied to it will count as a heading.
    # We can name additional styles to be picked up as headings by the TOC in this property and their TOC levels.
    field.custom_styles = 'Quote; 6; Intense Quote; 7'
    # By default, Styles/TOC levels are separated in the "custom_styles" property by a comma,
    # but we can set a custom delimiter in this property.
    doc.field_options.custom_toc_style_separator = ';'
    # Configure the field to exclude any headings that have TOC levels outside of this range.
    field.heading_level_range = '1-3'
    # The TOC will not display the page numbers of headings whose TOC levels are within this range.
    field.page_number_omitting_level_range = '2-5'
    # Set a custom string that will separate every heading from its page number.
    field.entry_separator = '-'
    field.insert_hyperlinks = True
    field.hide_in_web_layout = False
    field.preserve_line_breaks = True
    field.preserve_tabs = True
    field.use_paragraph_outline_level = False
    insert_new_page_with_heading(builder, 'First entry', 'Heading 1')
    builder.writeln('Paragraph text.')
    insert_new_page_with_heading(builder, 'Second entry', 'Heading 1')
    insert_new_page_with_heading(builder, 'Third entry', 'Quote')
    insert_new_page_with_heading(builder, 'Fourth entry', 'Intense Quote')
    # These two headings will have the page numbers omitted because they are within the "2-5" range.
    insert_new_page_with_heading(builder, 'Fifth entry', 'Heading 2')
    insert_new_page_with_heading(builder, 'Sixth entry', 'Heading 3')
    # This entry does not appear because "Heading 4" is outside of the "1-3" range that we have set earlier.
    insert_new_page_with_heading(builder, 'Seventh entry', 'Heading 4')
    builder.end_bookmark('MyBookmark')
    builder.writeln('Paragraph text.')
    # This entry does not appear because it is outside the bookmark specified by the TOC.
    insert_new_page_with_heading(builder, 'Eighth entry', 'Heading 1')
    self.assertEqual(' TOC  \\b MyBookmark \\t "Quote; 6; Intense Quote; 7" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w', field.get_field_code())
    field.update_page_numbers()
    doc.update_fields()
    doc.save(ARTIFACTS_DIR + 'Field.field_toc.docx')

def insert_new_page_with_heading(builder: aw.DocumentBuilder, caption_text: str, style_name: str):
    """Start a new page and insert a paragraph of a specified style."""
    builder.insert_break(aw.BreakType.PAGE_BREAK)
    original_style = builder.paragraph_format.style_name
    builder.paragraph_format.style = builder.document.styles.get_by_name(style_name)
    builder.writeln(caption_text)
    builder.paragraph_format.style = builder.document.styles.get_by_name(original_style)

FieldToc class

FieldToc class

Remarks

Constructors

Properties

Methods

Examples

See Also