mlreportgen.report.Chapter Class

Namespace: mlreportgen.report
Superclasses: mlreportgen.report.Section

Chapter reporter

Description

Use an object of the mlreportgen.report.Chapter class to add a chapter to a report.

The mlreportgen.report.Chapter class is a handle class.

Class Attributes

HandleCompatible

true

For information on class attributes, see Class Attributes.

Creation

Description

ch = mlreportgen.report.Chapter creates a reporter that generates a chapter. The chapter has a new page layout defined by the default template of the reporter.

The default template is a portrait page with a header and a footer. The header is empty. If a chapter is the first chapter of the report, the footer contains an automatically generated page number that starts with 1. If the chapter is not the first chapter, the page numbering continues from the last page of the previous chapter. Use the Layout property to override some of the page layout features of the chapter, such as the orientation.

Use the Title property to specify the title.

To add content to the chapter, use the append method of the mlreportgen.report.Chapter object.

Note

Before you add a chapter to a report, add all of the content to the chapter. Once you add the chapter to a report, you cannot add more content to the chapter.

ch = mlreportgen.report.Chapter(title) creates a chapter with the specified title. See the Title property.

ch = mlreportgen.report.Chapter(PropertyName=Value) sets properties using name-value arguments. You can specify multiple name-value arguments in any order.

Properties

Title — Chapter title

character vector | string scalar | DOM object | getTitleReporter reporter | ...

Chapter title, specified as one of these values:

• character vector or string scalar

• DOM object

• 1-by-N or N-by-1 array of string scalars or DOM objects

• 1-by-N or N-by-1 cell array of string scalars, character vectors, and DOM objects

• mlreportgen.report.Title object returned by the getTitleReporter method

The title appears at the beginning of the chapter and in the header of all chapter pages except the first page. The title also appears in the table of contents of the report.

Inline objects are objects that a paragraph can contain. If the title value is an inline object, the Chapter object uses a template from its template library to create a title based on the value. The template used to create the title depends on whether the title is numbered. A chapter title is numbered by default. To turn off numbering for this chapter, use the Numbered property. To turn off numbering for all other chapters in the report, use the mlreportgen.report.Section.number method.

If the title is numbered, the title is prefixed in English reports by a string of the form Chapter N, where N is the automatically generated chapter number. In some other locales, the English prefix is translated to the language of the locale. See the Locale property of mlreportgen.report.Report for a list of translated locales.

You can use inline DOM objects to override the character formatting specified by the chapter default title templates.

If the title value is a DOM paragraph or other DOM block object, the chapter inserts the object at the beginning of the chapter. If you use a DOM block object, you can use block elements to customize the spacing, alignment, and other properties of the chapter title. In this case, you must fully specify the title format and provide title numbering yourself.

Note

For the page headers to correctly display the title, the style name of the title must be SectionTitle1. If the title is specified as a DOM mlreportgen.dom.Paragraph object with no StyleName set, the StyleName property is automatically changed to the correct style name. You can customize the paragraph style by including DOM style objects in the Style property of the Paragraph object. If you use a custom template to format the title, make sure the style name used by the template is SectionTitle1. Customize the title style by modifying the SectionTitle1 style in the custom template.

Attributes:

GetAccess	public
SetAccess	public

Numbered — Whether to number this chapter

[] (default) | 1 (true) | 0 (false)

Whether to number this chapter, specified as a logical 1 (true) or 0 (false). When you specify:

• [] or 1 — Number the chapter relative to other chapters in the report. The chapter number appears in the title.

• 0 — Do not number the chapter.

The value of the Numbered property overrides the numbering specified for all report chapters by the mlreportgen.report.Chapter.number method.

Attributes:

GetAccess	public
SetAccess	public

Data Types: logical

Content — Content of this section

character vector | string scalar | inline object | ...

Content of the section, specified as one of these values:

• character vector or string scalar

• DOM objects that can be added to a DOM document part

• Reporters, including Section reporters

• 1xN or Nx1 array of string scalars or character vectors

• 1xN or Nx1 cell array of string scalars, character vectors, and DOM objects

Use the Chapter constructor or append method to set this property. You cannot set it directly.

Attributes:

GetAccess	public
SetAccess	public

Layout — Layout of this chapter

mlreportgen.report.ReporterLayout

Layout of this chapter, specified as an mlreportgen.report.ReporterLayout object. Use the properties of the ReporterLayout object to override some of the chapter layout properties that are defined in the template for the chapter.

Example: chapter.Layout.Landscape = true

Attributes:

GetAccess	public
SetAccess	public

TemplateSrc — Source of template for this reporter

character vector | string scalar | reporter or report | DOM document or document part

Source of the template for this reporter, specified in one of these ways:

• Character vector or string scalar that specifies the path of the file that contains the template for this reporter

• Reporter or report whose template this reporter uses or whose template library contains the template for this reporter

• Document Object Model (DOM) document or document part whose template this reporter uses or whose template library contains the template for this reporter

The specified template must be the same type as the report to which you append this reporter. For example, for a Microsoft^® Word report, TemplateSrc must be a Word reporter template. If the TemplateSrc property is empty, this reporter uses the default reporter template for the output type of the report.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true
Dependent	true

TemplateName — Name of template for this reporter

character vector | string scalar

Name of the template for this reporter, specified as a character vector or string scalar. The template for this reporter must be in the template library of the template specified by the TemplateSrc property of this reporter.

Attributes:

GetAccess	public
SetAccess	public

Data Types: char | string

LinkTarget — Hyperlink target for this reporter

[] (default) | character vector | string scalar | mlreportgen.dom.LinkTarget object

Hyperlink target for this reporter, specified as a character vector or string scalar that specifies the link target ID, or an mlreportgen.dom.LinkTarget object. A character vector or string scalar value converts to a LinkTarget object. The link target immediately precedes the content of this reporter in the output report.

Attributes:

GetAccess	public
SetAccess	public

Methods

Public Methods

append	Add content to chapter
add	(Not recommended) Add content to chapter
getTitleReporter	Get chapter title reporter
mlreportgen.report.Chapter.number	mlreportgen.report.Chapter.number(report,numbering) specifies whether to number chapters in a report. If numbering is true, all chapters in the report are numbered.
mlreportgen.report.Chapter.createTemplate	mlreportgen.report.Chapter.createTemplate(templatePath,type) creates a copy of the Chapter template specified by type at the location specified by templatePath. You can use this method to create a copy of a default Section template to serve as a starting point for creating your own custom template.
mlreportgen.report.Chapter.customizeReporter	mlreportgen.report.Chapter.customizeReporter(toClasspath) creates an empty class derived from the Chapter reporter class with the name toClasspath. You can use the generated class as a starting point for creating a custom version of the Chapter reporter.
mlreportgen.report.Chapter.getClassFolder	Get location of folder that contains mlreportgen.report.Chapter class definition file path = getClassFolder returns the path of the folder that contains the class definition file. Return Values path — Class definition file location, returned as a character vector For more information, see the method for the Reporter class, mlreportgen.report.Reporter.getClassFolder.
copy	Create copy of reporter object and make deep copies of property values copiedObj = copy(reporterObj) returns a copy of the specified reporter object. The returned copy contains a deep copy of any property value of reporterObj that references a reporter, DOM object, or mlreportgen.report.ReporterLayout object. As a result, you can modify the properties of the original or new object without affecting the other object. Input Arguments reporterObj — Reporter object to copy, specified as an object of a reporter class Return Values copiedObj — Copy of reporter, returned as an object of a reporter class For more information, see the method for the mlreportgen.report.Reporter class, copy.
getImpl	Get implementation of reporter impl = getImpl(reporter,report) returns the Document Object Model (DOM) object that implements the reporter, reporter, when you append it to the report, report. Note You cannot add content to the reporter after calling this method. Input Arguments reporterObj— Reporter object, specified as an object of mlreportgen.report.Reporter or an object of a subclass of mlreportgen.report.Reporter report — Report, specified as a mlreportgen.report.Report object Return Values impl — Implementation object, returned as a DOM object. For more information, see the method for the mlreportgen.report.Reporter class, getImpl.

Examples

Add a Chapter to a Report

Add a section to a chapter and the chapter to a report. Set the layout orientation of the chapter to landscape.

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

rpt = Report('My Report','pdf');

append(rpt,TitlePage(Title='My Report'));

chapter = Chapter('Images');
chapter.Layout.Landscape = true;
append(chapter,Section(Title='Boeing 747',Content=Image('b747.jpg')));

append(rpt,chapter);
close(rpt);
rptview(rpt);

Here is the first page of Chapter 1 in the generated report.

Version History

Introduced in R2017b

R2020b: add method is not recommended

Starting in R2020b, use the append method instead of the add method to add content to objects of these Report API classes:

• mlreportgen.report.Report

• mlreportgen.report.Chapter

• mlreportgen.report.Section

• slreportgen.report.Report

To add content to a DOM API object, such as an mlreportgen.dom.Paragraph object, continue to use the append method of the DOM object. The advantage of using append to add content to Report API objects is that you use the same method name as you use to add content to DOM API objects.

There are no plans to remove the add methods of the Report, Chapter, or Section classes. Report API programs that use the add methods will continue to run.

To update existing code, replace the method name add with append as shown by the examples in the table.

Not Recommended	Recommended
import mlreportgen.report.* import mlreportgen.dom.* rpt = Report("My Report","pdf"); ch = Chapter("My Chapter"); sect = Section("My Section"); para = Paragraph("My Content "); append(para,"more Content"); add(sect,para); add(ch,sect); add(rpt,ch); close(rpt); rptview(rpt);	import mlreportgen.report.* import mlreportgen.dom.* rpt = Report("My Report","pdf"); ch = Chapter("My Chapter"); sect = Section("My Section"); para = Paragraph("My Content "); append(para,"more Content"); append(sect,para); append(ch,sect); append(rpt,ch); close(rpt); rptview(rpt);