Skip to main content

Creating a table of contents

To create a table of contents in a document, the build-script should be setup to output TOC- and product-templates and additionally use the table of contents-library to enrich the table of contents after the document was populated. One requirement is, that each TOC-entry is placed with its own template (not all TOC-entries in the same template). The other requirement is, that templates of records, that should show up in the TOC, need a "Breadcrumb"-placeholder, which is used to detect on which pages the records are located.

Pre-building the TOC-pages​

If the table of contents should be placed in front of (product-)pages that will be listed in the toc, the TOC needs to be established before the product pages are, to not cause any page-conflicts by inserting TOC-pages in front of the product-templates that are already established.
For this, a productlist needs be created, that contains products for all the records, that will be established in the document later on and need to show up in the TOC. Each record should be mapped to a TOC-entry-template that may contain placeholders for product-specific information like productname, description, productimage. The placeholder for pagenumbers TOC Replace Pagenumber will be populated with the product-template's pagenumbers in a later step.

utils = comet.pyImport("[xml]/library/framework/utils.py")

productlist = [ 
    utils.create_comet_page(toc_page_template, toc_parent_page) 
]

record_ids = my_datasource_lib.find_entity_ids("product")
for id in record_ids:
    productlist.append(utils.create_comet_product(id, toc_template))

productlist.append(utils.create_comet_page(toc_page_template, toc_parent_page))

pages = comet.gDocument.getPages()
comet.product.establish(productlist, toc_page_template, toc_template, pages[-1])

TOC-entry-templates after the pre-build-step

Building the product-pages​

Next, the regular producttemplates can be established in the document. Before that is done, the last page of the TOC should be saved for later use. In the producttemplates, a placeholder needs to be used, that can be searched later on to determine the records for TOC-entries and their pagenumbers. For a standardized approach, we have added the placeholder TOC Record Breadcrumb.

pages = comet.gDocument.getPages()
LAST_TOC_PAGE_INDEX = pages[-1].getIndex()

record_ids = my_datasource_lib.find_entity_ids("product")
productlist = []
for id in record_ids:
    p_page = create_page(product_page_template, product_parent_page)
    productlist.append(p_page)
    p = create_product(id, product_template)
    productlist.append(p)
	
comet.product.establish(productlist, product_page_template, product_template, pages[-1])

Product-template with applied TOC-Breadcrumb-placeholder

Add pageinformation to the TOC​

After the product-pages are established, information about their records and corresponding pagenumbers can be looked up and addded to the TOC, that is already established.
For this, the occurrances of the "Breadcrumb"-placeholder are searched in the page-range after the TOC-pages. Their pagenumbers, string-Ids and (optionally) key-values are stored as TocEntry-objects and can be used to insert pagenumbers and add hyperlinks in the TOC. Instead of the breadcrumb-placeholder any other placeholder may be used to find records. However, this might cause varying results depending on how that placeholder is used in templates / the document.

PLACEHOLDER_FIND_RECORD = 200
page_range_products = comet.gDocument.getPages()[LAST_TOC_PAGE_INDEX:]

toc = toc_lib.TableOfContents({"type":"product","base_attributes":["label","id"],"attributes":["static_text_page"]}, page_range_products, placeholder_range=[PLACEHOLDER_FIND_RECORD])
LOGGER.wlog(f"Found TOC: {toc}")

page_range_toc = comet.gDocument.getPages()[:LAST_TOC_PAGE_INDEX+1]

PLACEHOLDER_REPLACE_PAGENUM = 201
toc.replace_pagenumbers(placeholder_id=PLACEHOLDER_REPLACE_PAGENUM, page_range=page_range_toc, hyperlink_type=comet.CTextModel)

PLACEHOLDER_SET_LINK = 202
toc.generate_page_hyperlinks(placeholder_id=PLACEHOLDER_SET_LINK, page_range=page_range_toc, hyperlink_type=comet.CTextModel)

TOC-entry-template with placeholder to replace pagenumber TOC-entry-templates with replaced pagenumber