mlreportgen.report.Report class

Package: mlreportgen.report

Report container

Description

An object of the mlreportgen.report.Report class is a container for a report based on reporters and MATLAB^® and DOM objects. Use an mlreportgen.report.Report object to generate an HTML, PDF, or Word report based on templates in a template library.

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

Class Attributes

HandleCompatible

true

For information on class attributes, see Class Attributes.

Creation

Description

report = mlreportgen.report.Report() returns a report container object with default property values.

report = mlreportgen.report.Report(path) sets the OutputPath property to path.

report = mlreportgen.report.Report(path,type) also sets the Type property to type.

report = mlreportgen.report.Report(path,type,template) also sets the TemplatePath property to template.

report = mlreportgen.report.Report(Name=Value) sets properties using name-value pairs. You can specify multiple name-value pair arguments in any order.

Properties

OutputPath — Path of the generated report file

character vector | string scalar

Path of generated report file, specified as a character vector or string scalar. The path is the location in the file system where the report output document is stored. The path can be a full path, for example, 'C:/myreports/reportA.docx'. The path can also be relative to the current MATLAB folder, for example, 'reportA'. If the file name does not have a file extension that corresponds to the Type property, the appropriate file extension is added.

Note

Generating a PDF report on a cloud drive, such as MATLAB Drive™, can result in an error that is caused by file contention between the report generation software and the cloud drive synchronization software. To avoid this error, generate reports on a local drive that does not synchronize with the cloud. Consider writing a script that generates a report on a local drive and then copies the report to the cloud drive.

PackageType — Packaging for generated files

'zipped' | 'unzipped' | 'both' | 'single-file'

Packaging used for the generated files, specified as one of the values in the table.

Value	Supported Report Types	Description
'zipped'	'docx'or 'html'	Generates the report as a zip file at the location specified by the OutputPath property. The zip file has an extension that matches the document type (docx for Word output or htmtx for HTML output.) For example, if the document type is docx and OutputPath is s:\docs\MyDoc, the output is packaged in a zip file named s:\docs\MyDoc.docx.
'unzipped'	'docx' or 'html'	Generates the report as separate files in a folder that has the file name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc, the output folder is s:\docs\MyDoc.
'both'	'docx' or 'html'	Generates zipped and unzipped outputs.
'single-file'	'pdf' or 'html-file'	Generates the report as a single file.

When the Type property is 'html', to generate an HTML report that you can open without unzipping, set PackageType to 'unzipped' or 'both'. In the folder that contains the generated files, open the root.html file.

Type — Output type

'pdf' (default) | 'html' | 'html-file' | 'docx'

Output type, specified as one of these values:

• 'pdf' – PDF file.

• 'html' – HTML report, packaged as a zipped file that contains the HTML file, images, style sheet, and JavaScript^® files of the report. To generate an HTML report as a folder that contains unzipped files, set the PackageType property to 'unzipped' or 'both'.

• 'html-file' – HTML report, consisting of a single HTML file that contains the text, style sheets, JavaScript, and base64-encoded images of the report.

• 'docx' – Microsoft^® Word document.

If you specify a template using the TemplatePath property, the value for Type must match the template type.

Layout — Page layout options

mlreportgen.report.ReportLayout object

Page layout options for this report, specified as an mlreportgen.report.ReportLayout object. The initial value of the Layout property is an mlreportgen.report.ReportLayout object with default values. Customize the page layout by modifying the property values. For an example, see Create a Landscape Report.

The layout options specified by the Layout property of objects of the mlreportgen.report.TitlePage, mlreportgen.report.TableOfContents, and mlreportgen.report.Chapter classes can override the page layout properties specified by the Layout property of an mlreportgen.report.Report object.

Note

The Layout property applies only to PDF and Word reports.

Locale — Locale or language

[] (default) | character vector | string scalar

Locale or language, specified as a character vector or string scalar that consists of the ISO_639-1 two-letter language code of the locale for which this report is to be generated. The default value, [], specifies the language of the system locale, for example, English on an English system. The Report API uses the language code to translate chapter title prefixes to the language of the specified locale. Translations are provided for the following locales: 'af', 'ca', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'eu', 'fi', 'fr', 'hu', 'id', 'it', 'ja', 'ko', 'nl', 'nn', 'no', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sr', 'sv', 'tr', 'uk', 'xh', and 'zh'. If you specify an unsupported locale, the English version is used. See https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.

For an example, see Translate Chapter Title Prefixes.

TemplatePath — Location of template

character vector | string scalar

Location of the template used to format this report, specified as a character vector or string scalar. You can use this property to specify a custom template for the report.

Document — Underlying DOM document object

mlreportgen.dom.Document

Underlying DOM document object used to generate the content of the report, specified as an mlreportgen.dom.Document object. This property is read-only.

Context — Report context

containers.Map object

Report context, specified as a containers.Map object that contains information to generate the report, such as the hierarchical level of the current report section. This property is read-only.

Debug — Debug mode

false or 0 (default) | true or 1

Debug mode, specified as a numeric or logical 1 (true) or 0 (false). If you set Debug to true or 1, the temporary files for the report are stored in a subfolder of the report folder and are not deleted when the report is closed.

Methods

Public Methods

open	Opens the report
append	Add content to report
add	(Not recommended) Add content to report
close	Close and generate report
rptview	Open generated report file in viewer
mlreportgen.report.Report.createTemplate	Create report template
mlreportgen.report.Report.customizeReport	Create class derived from Report class
mlreportgen.report.Report.getClassFolder	Report class definition file location
getTempPath	Path of report temporary directory
generateFileName	Generate temporary report file name
getReportLayout	Current page layout of report
fill	Fill report template holes
getContext	Get report context value
setContext	Set report context value
ispdf	Check if PDF report
isdocx	Check if Word report
ishtml	Check if multifile HTML report
ishtmlfile	Check if single-file HTML report

Examples

Create a Report

Create a report using the Report API.

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

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

Create the report container.

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

Add a title page, table of contents, and chapter to the report. The chapter contains two sections, each of which contains an image.

append(rpt,TitlePage(Title='My Report'));
append(rpt,TableOfContents);
ch = Chapter('Images');
append(ch,Section(Title='Boeing 747',...
    Content=Image(which('b747.jpg'))));
append(ch,Section(Title='Peppers',...
    Content=Image(which('peppers.png'))));
append(rpt,ch);
close(rpt);
rptview(rpt);

Create a Landscape Report

Create a report that has landscape orientation by using the Report API.

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

import mlreportgen.report.*

Create a report container. In the mlreportgen.report.ReportLayout object that is assigned to the Layout property, set the Landscape property to true.

rpt = Report('myreport','pdf');
rpt.Layout.Landscape = true;

Add content to the report. Generate and view the report.

append(rpt,TitlePage(Title='My Landscape Report'));
append(rpt,TableOfContents);
append(rpt,Chapter(Title='Tests'));
append(rpt,Chapter(Title='Unit Tests'));
close(rpt);
rptview(rpt);

Translate Chapter Title Prefixes

Translate chapter title prefixes to Japanese on an English system by setting the Locale property.

import mlreportgen.report.*
rpt = Report('Japanese Report');
rpt.Locale = 'ja';
house = char(23478); % Kanji character for house
append(rpt, Chapter(house));
close(rpt);
rptview(rpt); 

Version History

Introduced in R2017b

R2020b: add method is not recommended

Not recommended starting in R2020b

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

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);