Main Content

Create Lists of Captions and Titles of Related Report Elements in Report API Reports

In a Report API report, you can create a list of the captions or titles of related report elements, such as equations, so that you can browse the list and easily navigate to a particular report element. To create a list of report elements, use an mlreportgen.report.ListOfCaptions reporter.

Note

For a list of figures, use an mlreportgen.report.ListOfFigures reporter. For a list of tables, use an mlreportgen.report.ListOfTables reporter. See Create a List of Figures or Tables.

To use a ListOfCaptions reporter, you must create a paragraph for the caption or title of the report element. Then, associate the paragraph with an automatic numbering stream name that has a name that matches the automatic numbering stream name of the ListOfCaptions object.

A ListOfCaptions reporter creates a placeholder for a list in a new section of the report. Typically, you add a list of captions section after the table of contents and before the sections that contain the report content. In a PDF or Microsoft® Word reports, the list of captions is located where you put it in the report. In an HTML reports, the section is located in a sidebar.

The way the list of captions is generated depends on the report type:

Each list item in a list of captions links to a caption or title in the report. In PDF and Word reports, a list item also includes the page number of the caption or title in the report and a leader fills the space between the caption or title and the page number.

To create a list of captions:

  1. Create a Report API report.

  2. Create an mlreportgen.report.ListOfCaptions object.

  3. Specify the title of the list of captions section by setting the Title property of the ListofCaptions object.

  4. Choose a numbering stream name, for example, equation. Set the AutoNumberStreamName property of the ListOfCaptions object to the numbering stream name.

  5. Add the ListofCaptions object to the report.

  6. Create chapters or sections for the report content.

  7. Add content to the chapters or sections. Create mlreportgen.dom.Paragraph objects for the captions or titles of the report elements that you want to include in the list of captions. Use mlreportgen.dom.AutoNumber objects to associate the paragraphs with the same automatic numbering stream name that is assigned to the AutoNumberStreamName property of the ListofCaptions object.

  8. Close the report.

Create a Report That Has a List of Captions Section

This example shows how to create a list of captions section in a report. The example generates a report about physics equations and adds a list of the captions of the equations to the report.

Import the DOM and Report API packages so that you do not have to use long, fully qualified class names.

import mlreportgen.dom.*
import mlreportgen.report.*

Create a report.

rpt = Report("physics","docx");

Add a title page and a table of contents to the report.

tp = TitlePage();
tp.Title = "Physics Principles";
tp.Author = "John Doe";
append(rpt,TableOfContents);

Create a list of captions section.

loc = ListOfCaptions();
loc.Title = "List of Equations";

Define an automatic numbering stream name to use with the ListOFCaptions object.

equationStreamName = "equation";
loc.AutoNumberStreamName = equationStreamName;

Add the list of captions section to the report.

append(rpt,loc);

Create chapters for the report content. For this example, create two chapters. Each chapter has one equation.

Create the first chapter. Add a paragraph and add an equation to it.

ch1 = Chapter("Force");
append(ch1,Paragraph("Calculate force by multiplying mass and acceleration."));
eq1 = Equation("F = ma");
append(ch1,eq1);

Create a paragraph for the equation caption and associate the automatic numbering stream name with the caption.

caption1 = Paragraph("Equation ");
append(caption1,AutoNumber(equationStreamName));

Define a style for the captions. Include an mlreportgen.report.CounterInc object to increment the counter for the numbering stream.

equationCaptionsStyle = {HAlign("center"),CounterInc(equationStreamName),WhiteSpace("preserve")};
caption1.Style = equationCaptionsStyle;

Add the rest of the caption text and add the caption to the chapter.

append(caption1,".");
append(caption1," Force");
append(ch1,caption1);

Add the chapter to the report.

append(rpt,ch1);

Create the second chapter. Add a paragraph and add an equation to the paragraph.

ch2 = Chapter("Momentum");
append(ch2,Paragraph("Calculate momentum by multiplying mass and velocity."));
eq2 = Equation("p = mv");
append(ch2,eq2);

Create a paragraph for the equation caption and associate the automatic numbering stream name with the caption.

caption2 = Paragraph("Equation ");
append(caption2,AutoNumber(equationStreamName));

Specify the style for the caption.

caption2.Style = equationCaptionsStyle;

Add the rest of the caption text and add the caption to the chapter.

append(caption2,".");
append(caption2," Momentum");
append(ch2,caption2);

Add the chapter to the report.

append(rpt,ch2);

Close and view the report.

close(rpt);
rptview(rpt);

Here is the list of equations in the report:

Customize a List of Captions Section Title

You can specify the title of a list of captions section by setting the Title property of the ListOfCaptions reporter. To customize the style of the title, such as the font family, color, or size, use one of these approaches:

See Also

| |

Related Topics