Create Tables of Contents

You can add a table of contents to your report using the mlreportgen.report.TableOfContents class. This predefined class automatically adds a formatted table of contents that contains the report headings into your report. It is much easier and more efficient to use this class rather than using DOM objects to create a table of contents. For information and examples, see mlreportgen.report.TableOfContents.

Alternately, using DOM objects, you can create a table of contents in your report program or you can use a template to define the TOC. To create the TOC programmatically, append an mlreportgen.dom.TOC object to your report document.

Using a template ensures that all report programs that use that template create the same type of TOC. Also, with a template, you update the TOC in only one place if your formatting changes.

If you are using a template, you can either:

Include the TOC reference in your Word template or in your HTML or PDF template package (root.html).
Create a document part template for the TOC and insert the document part programmatically.

Using either approach, your report program must create heading objects that specify a numeric level or paragraph objects that specify outline level. The TOC generator uses content with level information to define the structure.

Create Tables of Contents in Report Programs

The DOM API supports automatic generation of a document’s table of contents. To enable automatic TOC generation:

Use Paragraph or heading objects (Heading, Heading1, and so on) in your document to specify section headings. If you use a Paragraph object for a heading, you must set the paragraph’s OutlineLevel property to an appropriate value, for example, 1 for a chapter or other top-level heading.
Insert a TOC placeholder in your document where you want to generate the TOC. You can insert a TOC placeholder programmatically or in the template for your document.

Create Tables of Contents Programmatically

To create a TOC placeholder programmatically, append an mlreportgen.dom.TOC object where you want to generate the TOC. You can specify the number of levels to include in the TOC and the type of leader. The default values are three levels and a dot leader. This example uses two levels and a dot leader.

import mlreportgen.dom.*;
d = Document('mydoc','pdf');
open(d);

title = append(d,Paragraph('My TOC Document'));
title.Bold = true;
title.FontSize = '28pt';

toc = append(d,TOC(2));
toc.Style = {PageBreakBefore(true)};

h1 = append(d,Heading1('Chapter 1'));
h1.Style = {PageBreakBefore(true)};
p1 = append(d,Paragraph('Hello World'));

h2 = append(d,Heading2('Section 1.1'));
h2.Style = {PageBreakBefore(true)};
p2 = append(d,Paragraph('Another page'));

h3 = append(d,Heading3('My Subsection 1.1.a'));
p3 = append(d, Paragraph('My Level 3 Heading Text'));

close(d);
rptview(d.OutputPath);

Use Templates to Create Microsoft Word Tables of Contents

You can use Word to insert a Word TOC reference object in a Word document or document part template. Word replaces the TOC reference with an automatically generated TOC when it updates the document.

To generate a table of contents in a DOM Word report using a template containing a TOC reference:

To specify where in the report to generate the TOC, create a table of contents reference in the Word template. See Create Word Table of Contents References.
Set the outline levels of the section heads that you want to appear in the table of contents. See Set Outline Levels of Section Heads.
Update the generated document. See Update Tables of Contents in Word Reports.

Create Word Table of Contents References

Open the template in Word.
Click where you want to create the table of contents.
On the References tab, click Table of Contents.
Select a TOC format option to generate a table of contents. For example, select the Built-In format option. The TOC appears.
Save the template.

Note

If you want to use a document part to insert a TOC, insert the TOC reference in the template for the document part. Delete the instance from the template before you save. See Create Microsoft Word Document Part Template Library and Use Document Parts to Programmatically Insert Placeholders for Tables of Contents.

Update Tables of Contents in Word Reports

You must update a Word document containing a TOC reference to generate a TOC. On Windows^® systems, the DOM API rptview command uses Word to update the Word document that it displays. If you open a Word document directly, for example, a document generated by the DOM API on system other than Windows, you must update the TOC.

In the Word template, select the TOC reference.
On the References tab, click Update Table.
In the Update Table of Contents dialog box, select Update entire table and click OK.

Create Table of Contents in HTML or PDF Templates

When you use a PDF or HTML template to add a TOC, you can:

Include a table of contents placeholder in the main template (root.html) in your template package.
Include the TOC placeholder in a document part template.

To create a table of contents in an HTML or PDF report using a document part template:

Define a document part template that includes the TOC placeholder.
Programmatically insert the document part into your report.
Use Paragraph or heading objects (Heading, Heading1, and so on) to specify your report’s headings. If you use a Paragraph object for a heading, you must set its OutlineLevel property to an appropriate value.

Define a Document Part Template for TOC

To create or modify a document part template for a TOC, use code in this form:

<dptemplate name="ReportTOC">
     <TOC number-of-levels ="3" leader-pattern="dots" />
</dptemplate>

You can:

Replace ReportTOC with the name you prefer
Set number-of-levels to the number of levels of headings you want to include in the TOC
Set leader-pattern to dots or to spaces

For an example, see PDF and HTML Document Parts and Holes.

Use Document Parts to Programmatically Insert Placeholders for Tables of Contents

Use the DocumentPart class to insert an instance of the document part that contains the TOC placeholder. If you define the document part template in your template, include the template package name when you define the document object. For example:

d = Document('MyReport','html','MyTemplate');

This code uses the supplied document part ReportTOC in the default template to generate a table of contents.

import mlreportgen.dom.*;
d = Document('MyReport','pdf');
append(d,'My Report');

append(d,DocumentPart(d,'ReportTOC'));
append(d,Heading1('Chapter 1'));
append(d,Heading2('Section 1'));

close(d);
rptview(d.OutputPath);

Tip

Use the variable assigned to the Document object in the DocumentPart syntax to uses the document part template associated with the document object:

append(d,DocumentPart(d,'ReportTOC'));

If you use this syntax, you do not need to call the template and specify the document type when you refer to the document part. This approach simplifies your code and generates the report more efficiently.

Set Outline Levels of Section Heads

To generate a table of contents in your report, your program must set the outline levels of the section heads that you want in the contents. An outline level is a paragraph format property that specifies whether and at what level a paragraph’s contents appear in a table of contents. For example, if a paragraph has an outline level of 1, the content appears at the top level of the generated table of contents. You can specify up to nine outline levels.

To set the outline level of paragraphs, use one of these approaches.

Use Template-Defined Styles to Set Outline Levels

You can use styles defined in the report’s template to set the outline level of a paragraph. By default Word documents include a set of styles, Heading 1, Heading 2, and so on, that define outline levels. Your program can use these built-in styles to specify for these heads to appear in the TOC. This example uses template-defined styles to set the outline levels of section heads and assumes that the template MyTemplate includes a TOC reference.

import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');

append(d,Paragraph('Chapter 1','Heading 1'));
append(d,Paragraph('Section 1','Heading 2'));

close(d);
rptview(d.OutputPath); % Updates the TOC

You can also use Word or an HTML editor to define your own heading styles and then use them to generate a report.

Use Format Objects to Set Outline Levels

You can use format objects to set outline levels. This example assumes that the template MyTemplate includes a TOC reference.

import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');

h1 = {FontFamily('Arial'),FontSize('16pt'),OutlineLevel(1)};
h2 = {FontFamily('Arial'),FontSize('14pt'),OutlineLevel(2)};
p = append(d,Paragraph('Chapter 1'));
p.Style = h1;
p = append(d,Paragraph('Section 1'));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

Use Heading Objects to Set Outline Levels

You can use mlreportgen.dom.Heading1 object (and Heading2, Heading3, and so on) to specify outline levels. A Heading1 object is a paragraph whose constructor specifies its outline level. You can use a Heading1 object alone or with template-based styles or format-object-based styles. This example assumes that the template MyTemplate includes a TOC reference.

import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');

h1 = {FontFamily('Arial'),FontSize('16pt')};
h2 = {FontFamily('Arial'),FontSize('14pt')};
h = append(d,Heading1('Chapter 1'));
h.Style = h1;
h = append(d,Heading2('Section 1'));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

In HTML and PDF reports, the Heading1 and Heading2 objects generate the HTML elements h1 and h2. By using the objects Heading1, Heading2, and so on, you can ensure that your report uses the default styles for headings.