Cookbook

Tables of contents (TOCs) show an index of items, made up by titles that link to those items in the document.

To work properly with TOCs, it is mandatory to know how they behave in MS Word and the different methods available in javadocx to add and customize them.

Add a TOC to the document

You can create a TOC with the addTableContents method, or using a pre-existent one in a template.

If you choose to dynamically generate it, type the following code:

This code asks for the automatic update of the TOC content with the autoUpdate parameter (see It is possible to update the TOC automatically when opening the document?, below) and then inserts the text that will show as a legend.

If you prefer to work with templates, you just need it to already have a TOC in its original content.

Adding items to the TOC

The items the TOC shows must have a heading level, which must be among the ones that the TOC admits.

If you add the TOC with the addTableContents method, the displayLevels option lets you define the number of levels it will show (excluding the second value). For example, to show just levels from one to three, write:

The default value of this option is to display all levels.

If you use a template, when creating the TOC with MS Word you can modify the Show levels option in its properties, in order to set the maximum value the TOC will display. The default value in MS Word is three.

When the TOC is placed in the document, being either created dynamically or previously added with a template, you can insert elements with the headingLevel option.

As an example, let's include a text with a heading level with a value of 2:

This same option is available in other methods like addDateAndHour and addHeading.

Besides headingLevel, you can also add items to the TOC by applying to the contents a paragraph style that has a value the TOC supports. You can achieve that with the outlineLvl option. For example, try this:

Styles for the legend and the TOC

The addTableContents method allows to assign styles to the legend you want to show to update the TOC. The available options are the same as with the addText method. E.g., to set bold style, colour and size of the text, code this:

If you need to change the style of the TOC you must generate a DOCX in Word with the appearance you wish, and then import it from your code:

MS Word lets you customize the styles for every TOC level. See Format a table of contents inside Related information in this same page.

Is it possible to add more than one TOC?

Just like MS Word lets you put more than one TOC with the option Custom Table of Contents, javadocx lets you create as many TOCs as necessary. Each TOC can have its own properties.

This example covers how to generate two TOCs in separate pages with different levels:

It is possible to update the TOC automatically when opening the document?

Due to safety reasons, MS Word disallows opening a document and place automatically the TOC, as this action requires an action from the user.

The autoUpdate option of the addTableContents method asks MS Word to update the TOC when opening the document, but doesn't force the program to do it.

As an alternative of this MS Word limitation, use the addList method to create a list of items that links to the corresponding pages with cross-references or add a macro in the document.

Generate the TOC automatically with the conversion plugin

The conversion plugin, available in the Advanced and Premium licenses, allows to generate automatically the TOC when transforming DOCX documents to other formats like PDF or HTML. Since javadocx 8, the conversion plugin can also generate TOCs in a DOCX.

In the packages of these licenses you can find the instructions to install it.

You can transform a DOCX with its TOC to PDF by executing:

You can generate the TOC of a DOCX by executing: